Resource Definitions

Custom MIME types should be accompanied with both machine- and human- readable definition documents to allow for both dynamic client generation and easier developer understanding of the expected responses.

For a more coherent discussion of this idea, watch my talk from RESTFest 2014.

JSON’s lack of a strong document definition format has left a gap that several API vendors have worked to fill. A number of technologies have emerged to define API endpoints as well as the expected formats of their requests and responses. Mashery continues to develop the I/O Docs format as a solution to build interactive documentation that can be served directly through the browser. This JSON-based format can also be used by developers to dynamically generate client code. Responding to requests made to the reserved “definition” endpoint with the snippet of I/O Docs code that corresponds to that resource can allow client developers to dynamically generate code to interact with your API and support resource-level changes as they occur.

Applying the same content negotiation rules for definitions, your API can support either multiple versions of the same definition language, or it may support many of the other definition languages currently vying to become standards, such as RAML and Swagger.

Leave a Reply

Your email address will not be published. Required fields are marked *