REST Web Service API - Naming Guidelines

The following offers a suggested set of URI naming guidelines for REST web service APIs that have worked for me in practice.

The book RESTful Web Services RESTful Web Services defines three basic rules for url design which act as a great starting point:
  • Use path variables to encode hierarchy: /parent/child 
  • Put punctuation characters in path variables to avoid implying hierarchy where none exists: /parent/child1;child2 
  • Use query variables to imply inputs into an algorithm, for example: /search?q=jellyfish&start=20 

 Other guidelines include:
  • URIs should ideally not change over time. 
  • Services offering a uniquely identifiable resource via a key should use basic rest notation (e.g. /accounts/(accountid) ) 
  • Services offering optional search/filtering capabilities should use query parameter ? key1 = value & key2 = value notation (e.g. /instruments?ticker=FT) 
  • Services expecting mandatory arguments over GET should have them as path variables (e.g. /accounthistory/(fromdate)/(todate)
  • All rest service names should use strict low case names (e.g. /client) 
  • The elements of the URI should map to business entities and the mapping should be consistent. For example a business entity named contentpartner should be consistently referred to as contentpartner(s) in all URIs (rather than a mix of partner, cp etc).  A good starting point would be the name of the domain object. 
  • Parameters that do not define a resource but qualify it (e.g. locale which feeds into the translations of the data) should not form part of the normal URI space.  Consider using headers or optional query parameters for these
  • Use nouns, not verbs.  The power of REST comes through the fact there is a limited verb set (operations) combined with a large set of nouns (or resources). Consequently the manner in which these nouns are constructed is of great importance. 
  • Avoid suffixes.  When designingURIs it is paramount that they refer to the thing that is being operated upon rather than the operation being performed. Secondly, the client is interested in the resource - not the implementation of the server software that powers the service. It is desirable to avoid suffixes such as .jsp or .aspx.
  • Use Accepts Header for content negotiation
  • Keep It Intuitive. URIs should be human readable or guessable. The easiest way to do this is to construct a URI hierarchy, grouping related items together. Such patterns of category and subcategory are very easy to understand. For example,