Because adding links in JSON should be easy
RESTful JSON is a minimal and pragmatic design pattern for using links to build expressive and evolvable APIs.
For JSON formats conforming to RFC 4627, apply the following guidelines:
- JSON objects MAY include a
url
property to indicate a link to itself - JSON objects MAY append
_url
to properties to indicate related links
All URLs SHOULD conform to RFC 3986. API providers MAY use camel case rather than snake case where applicable.
The JSON below shows a representation for an article.
{
"url": "http://example.com/articles/17",
"title": "Article Title",
"body": "The body of the article.",
"author_url": "http://example.com/authors/42",
"categories": [
{
"url": "http://example.com/categories/29",
"name": "Category A"
},
{
"url": "http://example.com/categories/33",
"name": "Category B"
}
],
"docs_url": "http://example.com/docs/article"
}
This example demonstrates using url
in an article resource object and included
categories, associating a related author resource with an author_url
link, and
referencing documentation with a docs_url
link.
At design time, all links that comply with the recommendations above SHOULD be documented indicating what each link means including any and all associated methods, query parameters, RFC 6570 URI templates and body properties.
API providers SHOULD consider adding the note below to their documentation to describe how links are used.
This API uses RESTful JSON by including links in the responses to guide client interactions. Objects in this API MAY include a
url
property for a link to itself and MAY append_url
to properties for related links.
API providers SHOULD reference the documentation in a response.
At runtime, only links a client is allowed to interact with SHOULD be present in API responses. If multiple methods are associated with a particular link, they MUST all be allowed if the link is present.
At build time, the client SHOULD NOT infer any meaning from nor hard-code any expectation of a link's URL structure. A client MAY introspect link URLs to populate documented query parameters or URI templates.
At runtime, the client SHOULD use links in API responses for interacting with resources. The client SHOULD rely on the presence or absence of links to know what it may or may not do at runtime. The client SHOULD ignore any resource links or properties it was not designed to use, allowing the server and client to evolve independently over time.
This document is influenced by APIs that have pragmatically added links to their APIs in a similar way: GitHub API, Stripe API, Medium API, Basecamp API, Trello API and Django REST Framework.
This document was authored by Stephen Mizell and Mark W. Foster in an effort to lower the barrier to entry for implementing and consuming hypermedia APIs. This document is licensed under the MIT license. The requirements here conform to RFC 2119.
RESTful JSON on GitHub.
Personally, I don't see what @netmilk is mentioning as a problem.