How many custom MIME types in a RESTful web API?

Question

Should a RESTful web API use a vendor-specific customized MIME type for each major class of resource (e.g. Customer, Reservation, HotelRoom, etc) or should the API share a single vendor-specific MIME type across all resources?

On one hand, each resource is different as it has different fields and for example an endpoint that might accept new Customers can't accept new Orders.

However, Rest Worst Practices suggests that this is A Bad Thing(tm) as this can over complicate parsing on the client side, but doesn't give much detail beyond that. I can definitely see this as a valid concern. Following the type-per-resource approach, it seems that you would perhaps even continue to create a custom type for each kind of collection w/ embedded non-anonymous entities.

Answer 1

Expanding the comment left by @deceze: You ain't gonna need it. Is it possible you're confusing "vendor-specific customized MIME types" with something else?

I don't see why you couldn't restrict yourself to sending out application/json or application/xml for all resources (or both, depending on the request).

Of course, the structure of each resource depends entirely on its respective fields, but you could still serve all of them as JSON hashes (if you're opting for JSON).

Answer 2

Think pragmatically. A MIME type is defined as, "Internet media type is a two-part identifier to standardize file-formats across the Internet." Meaning, if the format of the data is changing, (TXT->HTML->JSON->XML->YAML->CSV->...) the MIME type needs to change.

That said, there are other completely valid uses, one specifically mentioned by Joshua Belden above. Here is an example of how GitHub uses MIME type to determine the API version.

Current Version

By default, all requests receive the v3 version of the API. We encourage you to explicitly request this version via the Accept header.

Accept: application/vnd.github.v3+json

It makes sense that the data layout of a v2 request sent to the v3 version of the API would be incompatible even though they reside at the same URL (and vice versa). It also helps reduce the changes required to move from one version of the API to the next (you don't have to update URLs for example).

That said, it doesn't mean your application should by default use a custom MIME type in order to "future proof" for a version specific API. If your application does not have a large external facing API with many public consumers then you likely don't need a custom version MIME type.

Additionally, your REST API endpoints should be determining the structure of data produced and consumed, not the MIME type. For example, GET "/customers/5" should only produce data that was serialized from your Customer entity. And POST "/reservations" should only consume data that will properly de-serialize to your Reservation entity. Which means your endpoint's serialization will handle the syntax checking and should return a 400 level code and explain that the data provided is not structured properly.

Another example from GitHub's API that highlights this behavior.

 HTTP/1.1 422 Unprocessable Entity
 Content-Length: 149

 {
   "message": "Validation Failed",
   "errors": [
     {
       "resource": "Issue",
       "field": "title",
       "code": "missing_field"
     }
   ]
 }

To sum it all up, most serialization frameworks come "out of the box" expecting to process "application/json" and "application/xml". While you can certainly add a custom vendor specific MIME type, why do it if you don't have an overwhelming reason to do so?

Apologies if I just created a zombie question with this response.