Support Accept-HTTP Header application/json with a JSON response

[rrottmann]

Pasebins are often used in scripting and it is easier to parse JSON responses than dissecting the returned HTML code. To tell the server that a JSON response is desired, the client can add an Accept header with application/json to the request.

By default HTML response is expected and if requested, a JSON response should be similar to:

{
  "code": 201,
  "message": "Created",
  "url_ro": "http://localhost:8080/dog-sheep-fish",
  "url_rw: "http://localhost:8080/edit/dog-sheep-fish?token=jain3Ay5Hu5Pheez",
  "url_rm: "http://localhost:8080/remove/dog-sheep-fish?token=suoxaineiw1Cix1e",
  "burn_after": 10,
  "expiration": "24hour"
}

[albocc]

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.

[rrottmann]

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 with curl. 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 like jq.
• 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.

[albocc]

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)