Support Hypermedia

All our REST APIs MUST support hypermedia. Refer to Hypermedia and REST for a detailed explanation.

Our prefered way for hypermedia support is HAL. Other formats like Atom are also a valid choice. It is strongly recommended that the URLs generated by the API should be absolute URLs.

You can find more details about hypermedia formats in Hypermedia Response Formats.

Use RESTful URLs and actions

Separate your API in logical resources.

There should be two base URIs per resource. The first URL is for a collection

/products

The second is for a specific element in the collection.

/products/1234

Use HTTP verbs to operate on resources. Use Sub-Resources for relations. Refer to Collection Resources for more details.

Nouns are good - Verbs are bad

Use Nouns not Verbs when defining the API. The best is to have them in plural form because in most of the cases it returns a list or a couple of elements, not just one.

Use HTTP verbs to operate on the collections and elements

Use the HTTP verbs POST, GET, PUT, and DELETE. Think of them as mapping to the acronym, CRUD (Create-Read-Update-Delete).

Plural nouns and concrete names

Given that the first thing most people probably do with a RESTful API is a GET, we think it reads more easily and is more intuitive to use plural nouns.

Think about an API that exposes employees, customers and suppliers. An API that models everything at the highest level of abstraction and uses /parties is not intuitive. Developers do not understand how to use the API. It is more compelling and useful to see the resources listed as /employees, /customers, and /suppliers.

The level of abstraction depends on your scenario. You also want to expose a manageable number of resources. Aim for concrete naming and to keep the number of resources between 12 and 24.

Use sub-resources for Relations

Use sub-resources for related resources. Limit the nesting to one sub-resource.

Refer to Relationships and Sub-Resources for details.

Resource naming

Should you use hyphens, underscores, or camelCase to delimit words in the URIs?

There are many, many different articles and opinions about that. Finally we decided to go with underscores. This applies to URIs, field names, hypermedia labels and any other meta elements included in the response.

Use underscores. Do not use acronyms. Use small caps.

The following link led us to our reasoning. https://whathecode.wordpress.com/2011/02/10/camelcase-vs-underscores-scientific-showdown/.

Version the API

The URI should include /vN/ with the major version (N) as a prefix. No major.minor syntax.

In general do NOT increment the version of your API. Until you must. And it is really rare that you really must. Only increment on breaking changes. Extending the API is not a breaking change.

Refer to URI components for details. See Message Schema for a discussion of designing extensible message schemas.

Protect your API

You MUST protect your API.

Use appropriate standards for Authentication and Authorization. Use SSL everywhere - all the time

Refer to Security and Authentication for details.

Provide descriptive errors codes and messages

Use HTTP status codes.

Provide useful error message in a known consumable format

Refer to Error handling for details.

Facilitate caching

There are some reasons why you have to consider to use Caching

Refer to Caching for details.

Be consistent

Being consistent allows developers to predict and guess the method calls as they learn to work with your API. Being consistent also means that someone working with your API will be able to work with all of our APIs.

Things to avoid