Comments (3)
I agree, there should be a machine readable output as well and your idea of using the Accept
header make sense. However, I would not include the code
and message
in the response as that is already part of the HTTP protocol.
from microbin.
Thanks. Appreciate it!
Whether code and message are part of the JSON response are a matter of taste.
Rationale why it could be useful and can be seen in some APIs:
application/json
could be used from a shell together withcurl
. While it is possible to retrieve the response code, it is simpler to reduce the curl parameters and to dump the response JSON to file and loop over the output multiple times with the same tool likejq
.- an API can fuel a simple frontend and the response could be directly used to visualize the result
- small microservices might be linked together and a serverless json2html function might render message and code of the JSON response.
from microbin.
Thanks for the link! To me it looks like they are using the HTTP code as a business-level error code, too.
Depending on which design your API follows, this may be good or bad. These days most people tend to want to design their APIs according to the REST architecture, where the body of the request represents the resource being transferred. It also makes heavy use of HTTP's features like its verbs (GET
, PUT
, DELETE
, etc.) and response codes (e.g. 404 Not Found
, 409 Conflict
, etc.).
With REST in mind, I would see the status code and the associated message as being part of the HTTP protocol, i.e. as part of the header, as the body is (only) the resource.
For error responses on the other hand, REST does (AFAIK) not prescribe a format the data should be sent. In my experience you usually design your own error container that has some custom type that you pick. Here you could add the status code, but IMO it's repetitive at this point, since you usually work with the header already.
So, in REST it would typically look something like this:
Resource exists:
GET /my-resource/145 HTTP/1.1
Accept: application/vnd.mycompany.api.person+json
Host: api.example.com
HTTP/1.1 200 OK
Content-Type: application/vnd.mycompany.api.person+json
{
"name": "John",
"age": 42
}
Resource does not exist:
GET /my-resource/146 HTTP/1.1
Accept: application/vnd.mycompany.api.person+json
Host: api.example.com
HTTP/1.1 404 Not Found
Content-Type: application/vnd.mycompany.api.error+json
{
"message": "The requested resource could not be found",
"request_id": "123123-123123-123123"
}
However, the response could also be simple plain text, that's really up to the API designer.
I understand that parsing the header can be less ergonomic depending on the tools at hand, but generally, I would avoid designing an API around limitations of the current tooling, if possible.
Btw, I ran into the problem with curl
before as well and I usually solved it with the following snippet:
response=$(curl -s -w "%{http_code}\n" https://example.com/api/foo/bar)
status=$(tail -n 1 <<< $response)
body=$(head -n -1 <<< $response)
from microbin.
Related Issues (20)
- Burn After -> First Read gets 2 reads to create content HOT 3
- Can't support multiple file upload, seek support?
- Does MICROBIN_EDITABLE=false do anything? HOT 2
- Authenticate user while still following privacy settings
- Add way to healthcheck the docker image HOT 1
- Crash on create, no HTTP response HOT 6
- Looking forward to adding the function of QR code scanning and sharing HOT 1
- a better CLI way to use microbin HOT 2
- Unicode paste displayed as gibberish in raw text
- Special characters are escaped repeatedly
- MICROBIN_PUBLIC_PATH not working correctly HOT 1
- Still Maintained? HOT 11
- Feature Request: Autorsizing Text-Area and pressing TAB should insert a tab-stop or some spaces
- Uploader-Password not working as expected HOT 10
- Allow shorter pasta ID until a longer one is needed
- I cant save anything HOT 2
- If it is public let EVERYONE see it just with the URL (without any restriction) HOT 2
- backslashes keep doubling
- Problems with large files in docker
- Enable longer expiration periods
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from microbin.