JSON API — A specification for building APIs in JSON

September 27 2015, 4:34pm

Building a JSON API, you should be trying to follow the JSON API spec. Save your team the effort of arguing the best response format. It reached version 1.0 earlier this year, so it's safe to say there won't be too many big changes now.

It defines a standard for what the offsets in the json response should include: a resource is returned in "data", pagination in "links", errors in "errors", additional data in "meta", and a standard for including other objects aka "compound documents" in "relationships"/"included", so that instead of embedding other resource objects inside the main resource it flattens the graph of objects to eliminate duplicate data in the response (eg. the same user can be both the post author and a comment author).

If you're curious about some of the design decisions or how it compares to HAL, check out the FAQ.