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?

Answer 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.

Answer 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.

Answer 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.