General Overview about HTTP API Design
Thoughts on RESTful API Design
A document describing the experience the author, Geert Jansen, gained from designing the RESTful API for Red Hat’s Enterprise Virtualization product. Summarizes his thoughts about how a “good” REST Service should look.
https://restful-api-design.readthedocs.org/en/latest/
HTTP API Design Guide from Heroku
The Heroku team has published their HTTP API Design Guide. It is a short guide / best-practice collection, giving a nice overview which aspects you should consider when designing an API.
https://github.com/interagent/http-api-design
Data formats
Following two links describing how the response should be formatted: These are consistent, documented quasi-standards for use as response formats. Main topic is the linking and discoverability between resources.
JSON API :: A standard for building APIs in JSON.
Living document, written by Steve Klabnik and Yehuda Katz. Media-type: application/vnd.api+json
JSON HAL – Hypertext Application Language
Mike Kelly wrote down a convention expressing hyperlinks in JSON (or XML) and named it HAL. Media-type: application/hal+json
http://stateless.co/hal_specification.html, http://tools.ietf.org/html/draft-kelly-json-hal-06
Collection+JSON – Hypermedia Type
A format definition focused on collections. Media-Type: application/vnd.collection+json
http://amundsen.com/media-types/collection/
