I've been convinced by a fellow developer (now left) that the proper way to evolve RESTful web services is by creating custom media types for your services.
For example application/vnd.acme.payroll.v1+json
This way, you can tell your client to specify the encoding to use without changing the URI.
Is this technique a good one? Usually services embed the version into the url:
eg /acme/1.0/payroll/
I've had a lot of difficulty enforcing clients to use this scheme, especially as it seems DELETE does not enforce a media type
Common Media Types for RESTful APIs In the HTTP protocol, Media Types are specified with identifiers like text/html , application/json , and application/xml , which correspond to HTML, JSON, and XML respectively, the most common web formats.
Media type is a format of a request or response body data. Web service operations can accept and return data in different formats, the most common being JSON, XML and images.
There are a few main signaling mechanisms you can use in a RESTful service:
rel
of a resource you are linking to.Accept-Version
/Api-Version
.Each of these has distinct uses, and I will outline the ways in which we have come to understand them while designing our API.
To signal what operations are possible on a given resource, and what the semantics of these operations are, many use custom media types. In my opinion, this is not quite correct, and a rel
is more accurate.
A custom media type should tell you about the type of the data, e.g. its format or the way certain information is embodied or embedded. Having a custom media type means consumers of your API are tightly coupled to that specific representation. Whereas, using something more generic like application/json
says "this is just JSON data."
Usually JSON alone is not enough for a RESTful service, since it has no built-in linking or resource-embedding functionality. That is where something like HAL (application/hal+json
) comes in. It is a specialization of JSON that is still a generic format, and not application-specific. But it gives just enough to overlay the linking and embedding semantics on top of JSON that is necessary for coherently expressing a RESTful API.
rel
s)This brings us to rel
s. To me, a custom rel is a perfect way to signal what type of resource is being dealt with or linked to. For example, a custom rel
for a user resource might be http://rel.myapi.com/user
, which serves two purposes:
initialResource._links["http://rel.myapi.com/user"].href
.If you combine rel
s with a standard or semi-standard media type like application/hal+json
, you get resources which follow a uniform format specified by their media type, with API-specific semantics defined by their rel
s. This gets you almost all the way there.
The remaining question is versioning. How do you allow clients to negotiate different versions of the resource, while not invalidating old URIs?
Our solution, inspired by the Restify Node.js framework, is two custom headers: Accept-Version
from the client, which much match X-Api-Version
from the server (or Api-Version
in the upcoming Restify 2.0 release, as per the new RFC 6648). If they don't match, a 400 Bad Request
is the result.
I admit that custom media types are a fairly popular solution here. In my opinion they don't fit very well conceptually, in light of the above considerations, but you would not be doing something weird if you chose them as your versioning mechanism. It has some semantic issues when used with methods other than GET
though, as you note.
One thing to keep in mind is that in a truly RESTful system, versioning should not be such an issue. It should only matter in one very specific situation: when the representations of your resources change in backward-incompatible ways, but you still want to keep the same rel
s. So if the http://rel.myapi.com/friend
resource suddenly loses its username
field and gains an id
field, that would qualify. But if it suddenly gains a nickname
field, that's not backward-incompatible, so no versioning is needed. And if the concept of "friends" is completely replaced in your API with the concept of, say, "connection", this is not actually backward-incompatible, because API consumers will simply no longer find http://rel.myapi.com/friend
links anywhere in the API for them to follow.
Yes, it's a good option. It clarifies the encoding you'll be using for payloads and lets both sides negotiate a different version of the encoding without changing the URI, as you correctly pointed out.
And yes, there's no need for a client to send a DELETE along with an entity-body. I believe it will simply be ignored by a compliant HTTP server, given that no payload data is transferred in that case. The client issues a DELETE for a URI, and the server returns a response code indicating whether it succeeded. Nice and simple! If the server wishes to return some data after a DELETE then it is free to do so, and should specify the media type of the response when it does.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With