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
The second is for a specific element in the collection.
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
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
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.
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.
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.
There are some reasons why you have to consider to use Caching
- improve Speed
- reduce latency
- reduce server load
- reduce network traffic
Refer to Caching for details.
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
- Do not query args on an non-query/non-search resource. e.g. use
- Do not use mixed or upper-case in URIs.
- Avoid extensions (avoid
- Do not use characters that require url encoding in URIs (e.g. spaces).