I'm building an API, and for the most part there will be JSON and HTML content there. But a few very specific endpoints only render true or false, and also accept true or false in POST. That is the entire body of the request or response.
What would be the correct content-type header for this resource?
I'm using text/plain. application/text also sounds ok, though it I haven't found it used anywhere else (is it?)
The single words true or false are valid JSON so may use application/json with these values.
However, it is recommended that your JSON messages be either an object or an array as some software may not work properly if this is not the case. To follow that recommendation you might instead return a value such as
{"result":true}
Related
I'm trying to add a new content type to a REST endpoint. Currently it only returns json but I now need to be able to return also a CSV file.
As far as I know, the best way to do this is by using the Accept header with value text/csv and then add a converter that is able to react to this and convert the returned body to the proper CSV representation.
I've been able to do this but then I have a problem handling exceptions. Up until know, all the errors returned are in json. The frontend expects any 500 status code to contain a specific body with the error. But now, by adding the option to return either application/json or text/csv to my endpoint, in case of an error, the converter to be used to transform the body is going to be either the jackson converter or my custom one depending on the Accept header passed. Moreover, my frontend is going to need to read the content-type returned and parse the value based on the type of representation returned.
Is this the normal approach to handle this situation?
A faster workaround would be to forget about the Accept header and include a url parameter indicating the format expected. Doing it this way, I'd be able to change the content-type of the response and the parsing of the data directly in the controller as the GET request won't include any Accept header and it will be able to accept anything. There are some parts of the code already doing this where the only expected response format is CSV so I'm going to have a difficult time defending the use of the Accept header unless there is a better way of handling this.
my frontend is going to need to read the content-type returned and parse the value based on the type of representation returned.
Is this the normal approach to handle this situation?
Yes.
For example, RFC 7807 describes a common format for describing problems. So the server would send an application/problem+json or an application/problem+xml representation of the issue in the response, along with the usual meta data in the headers.
Consumers that understand application/problem+json can parse the data with in, and forward a useful description of the problem to the user/logs whatever. Consumers that don't understand that representation are limited to acting on the information in the headers.
A faster workaround would be to forget about the Accept header and include a url parameter indicating the format expected.
That's also fine -- more precisely, you can have a different resource responsible for the each of the different media-types that you support.
It may be useful to review section 3.4 of RFC 7231, which describes the semantics of content negotiation.
I am currently contributing to a REST API written in Go and I was facing an existential question.
How are we supposed to handle an empty body in a PATCH? Knowing that a PATCH is used to update an existing data, are we supposed to return an error code (4XX) or an ok status (2XX)?
For example, if I have the following route: /user/:id
And a user has the following structure:
type User struct {
Name string
Email string
}
So if we PATCH a specific user, we will either have a body containing the name or the email.
What should we do if it is empty?
The RFC5789 was not a real help (2.2 for error handling)
https://datatracker.ietf.org/doc/rfc5789/?include_text=1
How are we supposed to handle an empty body in a PATCH?
That depends: what's wrong with an empty patch body?
If an empty patch body is an error, then your response should communicate the nature of the error to the client.
If the empty patch body is not an error, then apply the empty patch. That's probably a no-op, in which case, success! So you return a response that explains that applying empty patches is trivial, and here's where they can go to see the updated implementation. Alternatively, you can 204 as shown in the example. I don't see things explicitly spelled out, but I think you can draw upon the pattern described in RFC 7231 section 6.3.1.
Some examples that might help.
Suppose the client were using JSON Patch as the media type for the request. Now, a "JSON Patch document is a JSON [RFC4627] document that represents an array of objects". An empty request body is not a valid JSON document, and certainly isn't a valid array of objects, so that's a malformed patch document, and as described in section 2.2 you should be thinking about sending a 400 response.
Suppose the client were to send a json patch with an empty array of operations
[]
Semantically, that's a no-op -- except that a response indicating that the patch was successfully applied will invalidate cached values. So you could certainly report success (200) with not doing anything. You may be able to prevent the cached entries from being invalidated by returning an error (I think the Patch spec isn't quite describing the semantics correctly, but I don't see an errata filed).
A similar argument applies for application/merge-patch+json.
You may also want to consider the errata for RFC 5789
If a server receives a PATCH request with a media type whose specification does not define semantics specific to PATCH, the server SHOULD reject the request by returning the 415 Unsupported Media Type status code, unless a more specific error status code takes priority.
In particular, servers SHOULD NOT assume PATCH semantics for generic media types that don't define them, such as "application/xml" or "application/json".
The MDN used 204 No Content in an example here:
https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH#response
Resource 123 has a current configuration state and a default configuration state, and both of these configuration states can be represented by JSON.
A GET request to http://example.com/123/config will return the current configuration state, and a GET request to http://example.com/123/config?reset=true will return the default configuration state.
How should an API interpret boolean values? For instance:
http://example.com/123/config?reset=true
http://example.com/123/config?reset=blablabla
http://example.com/123/config?reset=false
http://example.com/123/config?reset=1
http://example.com/123/config?reset=0
http://example.com/123/config?reset=
http://example.com/123/config?reset
True and false
The true and false literals are just fine to represent boolean values. They are quite descriptive and, if your API supports JSON, true and false are definitively the obvious choices.
Enumerations
In a few situations, however, you may want to avoid boolean values because they cannot be expanded. You may want to consider enumerations instead.
It may be a poor comparison but it might help you to get the main idea of this approach: have a look at CSS properties such as overflow or visibility. They allow expandable values instead of only true or false. So new values can be easily added without changing the property names.
So, for the situation described in your question, to retrieve the default state of a resource, I would support a query parameter such as status, that could have values such as default and current.
The following would return the default state of the resource:
GET /config?status=default HTTP/1.1
Host: example.com
Accept: application/json
And the following would return the current state of the resource:
GET /config?status=current HTTP/1.1
Host: example.com
Accept: application/json
If no query parameter is provided, you could that the client wants the current state of the resource.
If you need to restore the resource state to its default state, consider using PUT, sending the new representation of the resource in the request payload. Something like:
PUT /config/status HTTP/1.1
Host: example.com
Content-Type: application/json
{
"value": "default"
}
Whichever way you want it to, it's completely up to you as the architect/designer. true/false is the most syntactically correct version, make sure that one works and add the other options as sugar if you want.
I want the user to have the opportunity to choose the format in which it receives a response from the server, whether it is plain text, json or xml. It's looks like I must to retrieve media_type by calling cowboy_req:meta/{2,3} and then use it for encoding a response body. But that value doesn't available in callbacks before content_types_provided (malformed_request, is_authorized, forbidden...).
Should I dublicate a cowboy logic and write my own code to determine media_type?
Or ignore all callbacks which had executed before the media_type has been determined.
Or maybe should I to place my response message into request metadata and encode it in the onresponse hook, then replace response body?
How should I do that?
I think you are not quite wright. Straight from init/3 and rest_init/3 functions the Request parameter is "full request", and you can read any header or meta in each callback.
And personally i would go with Header over Meta (since there is already Content-Type header defined, and Headers should take presence over Meta).
In general the REST callbacks in cowboy should only give you easily understandable workflow for handling request, with additional default response codes. In is_authorized/2 all you need to do is check authorization, simply return true or false (as part of tuple), and cowboy will either move forward with you logic or return 401 code. Checking is someone allowed to make request should not be determined on response format, but still, if you would like to do it, just read this Meta from Req parameter, and return true/false based on it.
And the only difference with content_types_provided/2 is that you return kind of bindings between Content-Types header values and your functions. I think all you need could be based on this official example
Every single resource I'va come across on Internet always describes very well what you can do with the GET operation, how it works and so on, bu it never explains the POST/PUT/DELETE and particularly the format of the data you pass in the HTTP body (I'm using JSON). It always says "you can make a post request and pass the appropriate data in the body".
I am struggling with what I can do and not. For example I want to know if it is possible to update one field of one entry by just sending the updated value, and not the entire object.
Is there any document that explains clearly the possibilities and limitations?
Thanks a lot.
Easy to read documentation is here: http://www.odata.org/developers/protocols
If you want all the dirty details and a strict language you can read this document: http://msdn.microsoft.com/en-us/library/dd541188(PROT.10).aspx
You can modify a value of a single property by sending a PUT request.
For example if you send a GET to this URL:
http://services.odata.org/(S(kupqbta5wqnfz2cln1qk052x))/OData/OData.svc/Products(0)/Name
And you request JSON (through an Accept header) the response will be:
{
"d" : {
"Name": "Bread"
}
}
The "d" wrapper is there only to avoid XSS attacks so that must not be included in the requests, but the rest stays the same, so if you then send a PUT request like this:
PUT http://services.odata.org/(S(kupqbta5wqnfz2cln1qk052x))/OData/OData.svc/Products(0)/Name HTTP/1.1
Host: services.odata.org
Content-Type: application/json
Content-Length: 20
{
"Name": "Meat"
}
It will update the property Name to value Meat. You can also send a PUT to the value itself, in which case the URL would end with $value (denotes the raw value of the property) like this:
PUT http://services.odata.org/(S(kupqbta5wqnfz2cln1qk052x))/OData/OData.svc/Products(0)/Name/$value HTTP/1.1
Host: services.odata.org
Content-Type: text/plain
Content-Length: 4
Meat
Note that this only works on primitive properties though.
The sample service on the odata.org allows you to make modifications (guarded by the session key in the URL), so can play with it there.
Google for the HTTP 1.1 specification.