How to create a custom media type (application/vnd) for a RESTful web service?

Question

I'm playing with REST right now and thought I properly implement HATEOAS just to get all concepts right.

For that I want to create my own media types (application/vnd[...]+xml and application/vnd[...]+json).

One first question: Does the media type define the contract between my server and client?

The media type will define my message formats so I need to add XML schema and JSON schema to go with the new media types (so that REST clients know what's coming in messages and what to send back).

I've done some research on the web but the details of how one does this are missing. Does it only involve writing exhaustive specification/documentations or are there some technical steps to implement? (I don't have to register it with IANA do I?)

How can a new - fully functional - application/vnd media type be created? and what do you need to take care of so that clients can properly use it?

Solution 1

@JohnDoDo

One first question: Does the media type define the contract between my server and client?

Yes, media type is one part of the contract. Contract in REST API is not static unlike SOAP(i.e. WSDL). Contract is defined by combination of underlying protocol(i.e. HTTP), URIs and Media Types(it's not prohibited to use several media types together). Media type defines data model, processing model, hypermedia controls(i.e. annotated links, input forms etc...) and support to include additional application specific information described by link relations, element names, ids, class names etc...

The media type will define my message formats so I need to add XML schema and JSON schema to go with the new media types (so that REST clients know what's coming in messages and what to send back).

You only need to define generic schemas which cover structure of the document. You do not need to define separate schemas for particular messages. Your messages must feet in the structure defined by media type.

How can a new - fully functional - application/vnd media type be created? and what do you need to take care of so that clients can properly use it?

1. Describe it(i.e. write format specification);
2. Register with IANA: http://www.iana.org/cgi-bin/mediatypes.pl registering media type under vnd.* tree takes nearly one week to register.

Solution 2

Have a look at A RESTful Hypermedia API in Three Easy Steps

Your media-type should describe the data types, but I wouldn't do it with an XML schema. If you use an XML schema, I strongly recommend you use a Loose versioning strategy, otherwise you'll find you'll need a new media-type every time you want to add a new element or attribute.

Solution 3

Does the media type define the contract between my server and client?

No, the media type only defines the type (e.g. application) and sub-type (e.g json) of the data

How can a new - fully functional - application/vnd media type be created? and what do you need to take care of so that clients can properly use it? (http://www.ietf.org/rfc/rfc2046.txt?number=2046)

If you decide to create your own custom media sub-type and expect it to be widely used, it should be registered with the IANA (http://www.iana.org/assignments/media-types). This is a standard way for sharing out-of-band information with potential clients.

Comments

[JohnDoDo]

So if I understood this correctly: It's just having a good document describing the media type so that developers know how to code the client?

[Tom Howard]

correct, and they need to resist the urge optimise by having their clients going directly to specific URLs. The client starts at well know root URI (e.g., example.org/list) and simply follows the links and forms to get to where it wants. e.g., GET example.org/list tells me that I can get the open items at example.org/list/?open. It's tempting for devs to bake that into their client, but tomorrow GET example.org/list might tell us that open items are at GET example.org/openlist or even otherexample.org/list

[Tom Howard]

I should also mention that you should be trying to minimise the out-of-band information that is communicated in your media-type document and maximise the in-band information that the client can receive from responses. The more out-of-band information your clients rely on, the more tightly coupled they will be to your server, making it difficult to evolve.

[JohnDoDo]

By out-of-bound information you mean not to define URL formats and locations or also limit the information about the content of the message? (e.g. you suggested not to add a XML/JSON schema in your answer). This is another issue I have with the resources I've read. I understand that navigation should not be a priory information for the client but how about message content!? The client needs a priory information about the content of messages to send/receive otherwise it will not know what to do with the messages? Correct? Or am I missing something?

[Tom Howard]

In terms of the responses your client received, yes it will expect a certain response; however the client shouldn't care if there is extra information in the response. In terms of the requests you send, this should be determined solely by the links and forms in the responses you receive.

[JohnDoDo]

Thanks a lot for this! So at the end of the day all it takes is just a solid written specification. Correct?

[Wim Deblauwe]

For clarity about point 2: It is advised to register it, but it is not a strict requirement. See stackoverflow.com/questions/29121241/…