How many user-defined MIME types are in a RESTful web interface?

Question

Should the RESTful web API use an individual MIME type for a specific core resource (e.g. Customer, Reservation, HotelRoom, etc.), or should the API use one provider-specific MIME type for all resources?

On the one hand, each resource is different in that it has different fields, and, for example, an endpoint that can accept new Clients cannot accept new Orders.

However, Rest Worst Practices suggests that this is A Bad Thing (tm), as this can complicate parsing on the client side, but does not provide details beyond that. I definitely see this as a valid issue. Following a type approach to a resource, it seems that you might even continue to create a custom type for each type of collection with built-in non-anonymous objects.

Answer 1

Extending the comment left by @deceze: You won’t need it. Is it possible that you are misleading “custom vendor-specific MIME types” with something else?

I do not understand why you could not limit yourself to sending application/json or application/xml for all resources (or both, depending on the request).

Of course, the structure of each resource depends entirely on the corresponding fields, but you can still serve all of them as JSON hashes (if you choose JSON).

Answer 2

Think pragmatically. The MIME type is defined as "The type of Internet media is a two-component identifier for standardizing file formats over the Internet." Value, if the data format is changed (TXT-> HTML-> JSON-> XML-> YAML-> CSV → ...), you need to change the MIME type.

However, there are other legitimate uses that are specifically mentioned by Joshua Belden above. The following is an example of how GitHub uses the MIME type to determine the version of the API.

Current version

By default, all requests receive API version v3. We ask you to explicitly request this version using the Accept header.

Accept: application / vnd.github.v3 + json

It makes sense that the data layout of the v2 request sent to the API version of v3 will be incompatible, even if they are on the same URL (and vice versa). It also helps to reduce the changes needed to move from one version of the API to the next (you do not need to update URLs, for example).

However, this does not mean that your application should, by default, use a custom MIME type for “future proof” for the version-specific API. If your application does not have a large external API with many public consumers, you most likely do not need the MIME type for the user version.

In addition, the REST API endpoints should determine the structure of the data being created and consumed, and not the MIME type. For example, GET "/ clients / 5" should only produce data that has been serialized from your Customer object. And the POST "/ reservation" should only consume data that is properly de-serialized for your reservation. This means that your endpoint serialization will handle syntax checking and should return level 400 code and explain that the data provided is not structured properly.

Another example from the GitHub API that emphasizes this behavior.

  HTTP/1.1 422 Unprocessable Entity Content-Length: 149 { "message": "Validation Failed", "errors": [ { "resource": "Issue", "field": "title", "code": "missing_field" } ] } 

To summarize, most serialization schemes go out of the box, waiting for processing of "application / json" and "application / xml". Although you can certainly add an individual MIME type for a specific provider, why do this if you have no reason to?

Sorry if I just created a zombie question with this answer.

Answer 3

If the RESTful web API uses an individual MIME type for a specific provider for each main resource class (for example, client, reservation, HotelRoom, etc.), or if the API shares one MIME for a specific provider type in all resources?

This does not really matter, since it doesn’t actually separate the client from the server, it’s just a rude decision.

However, Rest Worst Practices suggests that this is A Bad Thing (tm) as it may complicate client-side parsing, but does not provide much more than

Yes it's true. You should use fine-grained solutions like RDF with standard dictionaries like open related data and possibly hydra for the REST part.

Answer 4

Using MIME types allows you to separate a REST resource from its presentation (i.e. json, xml, pdf, etc.). This makes things less connected, but the ideation should not use it to determine the layout of the resource, but its format.

On the one hand, each resource is different in that it has different fields, and, for example, an endpoint that can accept new customers cannot accept new orders.

This, if I did not understand at all, could be achieved by the correct identification of resources.

Responding directly to your question: try as few custom MIME types as possible. IMHO you can use them to declare different versions of your API, as mentioned here.