Naming REST APIs

Guidelines for naming your REST APIs.

  • Use nouns to represent resources. Example – /books/{id}
  • Use plural to represent collection of resources – /books
  • Use verb to represent an executable action on a resource – /users/{id}/cart/check-out
  • Use HTTP methods for CRUD on the resource represented by URIs.
  • Use query strings for operations such as filtering, sorting and pagination.
  • Use - to improve readability.
  • Do not end the URI with /
  • Use lowercase letters.
  • Do not add file extensions in URI.
  • It may not be a great practice to force version number in URI. It could be used for debugging purposes. URI without version number should point to the latest version.
  • JSON is the right output format.
  • Use hyperlinks within response for better navigation (HATEOAS)
  • Use HTTP status code to handle errors.
Naming REST APIs