Confusion Between Noun vs. Verb in Rest URLs

by

Some snippets from the REST API Design Rulebook about different resource types:

Document

A document resource is a singular concept that is akin to an object instance or database
record.

Example:
http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet

Collection

A collection resource is a server-managed directory of resources. Clients may propose
new resources to be added to a collection. However, it is up to the collection to choose
to create a new resource, or not.

Example: http://api.soccer.restapi.org/leagues/seattle/teams

Store

A store is a client-managed resource repository. A store resource lets an API client put
resources in, get them back out, and decide when to delete them. On their own, stores
do not create new resources; therefore a store never generates new URIs. Instead, each
stored resource has a URI that was chosen by a client when it was initially put into the
store.

Example: PUT /users/1234/favorites/alonso

Controller

A controller resource models a procedural concept. Controller resources are like executable functions, with parameters and return values; inputs and outputs.

Like a traditional web application’s use of HTML forms, a REST API relies on controller
resources to perform application-specific actions that cannot be logically mapped to
one of the standard methods (create, retrieve, update, and delete, also known as
CRUD).

Controller names typically appear as the last segment in a URI path, with no child
resources to follow them in the hierarchy.

Example: POST /alerts/245743/resend

Based on the definitions in the book, the URIs you’ve posted probably fall under the Controller resource type, of which the book later states:

Rule: A verb or verb phrase should be used for controller names

Examples:

  • http://api.college.restapi.org/students/morgan/register
  • http://api.example.restapi.org/lists/4324/dedupe
  • http://api.ognom.restapi.org/dbs/reindex
  • http://api.build.restapi.org/qa/nightly/runTestSuite

Other naming rules, just for completeness

  • Rule: A singular noun should be used for document names
  • Rule: A plural noun should be used for collection names
  • Rule: A plural noun should be used for store names

Leave a Comment