API design: HATEOAS, json, versioning, and media types

Question

I like the REST HATEOAS concept of making your API discoverable through hyperlinks. People like XML with ATOM format for links and you might not even need to version your API. But, I'm only doing JSON and I want to version my API and still do HATEOAS.

It seems that a best practice would be to use a vendor media type as in application/vnd.me.v1+json but then there is all this talk about no format for hyperlinks in JSON and things like HAL, JSON+Collecton, and Siren which have their own media type.

So, here's my confusion. First, why specify a format through media type? Why can't the inclusion of links in JSON just be a convention that clients follow? Isn't that how hm-json browser discovers links?

And, if it must be defined as a media type, does something like this work?

application/vnd.me.v1.hal+json

Anyone?

Answer 1

First, why specify a format through media type?

Yes, you could have a convention for the format of the links, however, any convention could only be discovered after unpacking the body of the HTTP message. Since media types are headers, the body of the message can be accepted or rejected as an entire unit. This makes processing requests more efficient for consumers that do not support the media types offered.

application/vnd.me.v1.hal+json

As far as I understand, media types can be scoped to a level that fits the API you are describing. So, you could choose to have a media type for a single representation, a group of representations that all adhere to the same service, or a single media type for the entire organization.

This is a good SO post considering media types: