restful-json.md

RESTful JSON

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.

Overview

For JSON formats conforming to RFC 4627, apply the following guidelines:

1. JSON objects MAY include a url property to indicate a link to itself
2. 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.

Example

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.

Usage and Guidelines

API Providers (Server-Side)

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.

API Consumers (Client-Side)

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.

Influences

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.

About

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.

I absolutely love the idea of lowering the barrier to linked APIs this way! I have only one concern: The RESTful JSON url property can easily conflict with a property of a same name in the already existing data. It could be a breaking change for the brownfield scenario when API providers already have some API and existing integrations/clients.

What about restful_url and "_restful_url" ?

Or some ugly prefix: _url and "__"

Also - If the API MAY use camel case rather snake case, does this apply to the entire API, RESTful JSON URLs or both? It would be awesome to have some multi-word keys in the examples

{
  "camelCase": "value",
  "camelHump_url": "http://cairo.eg/humps/1"
}

or

{
  "snake_case": "value",
  "snake_nest_url": "http://amazonia.br/nests/1"
}

or

{
  "snake_case": "value",
  "camelHump_url": "http://cairo.eg/humps/1"
}

Personally, I don't see what @netmilk is mentioning as a problem.

However, I'd like to see a note on nesting "foreign keys" (https://adidas-group.gitbooks.io/api-guidelines/content/message/foreign-key-relations.html) e.g. is it expected / recommended to use:

{
   "author_url": ""
}

versus

{
   "author":  {
       "url": ""
   }
}

My opinion is that if we include (embed) and author, then the:

author: {
'url': '...'.
'other': 'data'
}

Makes sense. However, the spirit of less verbosity, if it is just a url relation, then I prefer author_url as the foreign relation personally.

author_url: "..."