Wiki

Clone wiki

rest-api-blueprint / ResourceNaming

Brief notes on general good practice on naming URL resources:

  • Avoid verbs in the URLs (HTTP methods are the verbs)
    • The exception is non-resource URLs for performing utility functions (not RESTful, but practical API)
  • Use plural nouns as they generally read better; at least be consistent
  • Use concrete nouns rather than abstract ones such as /items, /values, /things.
    • Note that popular API's use both
  • Expected meaning of operations on /people
    • POST - create a new person
    • GET - list all people
    • PUT - bulk update people
    • DELETE - delete all people
  • Expected meaning of operations on /people/tim
    • POST - error i.e. not allowed
    • GET - get details on person tim
    • PUT - create or update person tim
    • DELETE - delete tim

Aspects to consider when deciding whether to use URL paths or query strings on resources identified by multiple parts:

  • Query string parts are optional, and the endpoint should be meaningful when they are absent.
  • For GET on missing resources
    • if using a url path, return a 404
    • if using a query string, return an empty list
  • URL paths make sense when order is important (e.g. forming sub-hierarchy), and when sub-paths make sense
  • See also http://www.ietf.org/rfc/rfc3986 and http://tools.ietf.org/html/rfc6570

Updated