Resource Naming

The root resource name in the URL MUST be a noun and MUST be in the plural form. For example, a specific Shipper resource would be retrieved using:

GET /shippers/{shipperId}

…as opposed to:

GET /shipper/{shipperId}

Once a single resource has been identified (e.g. by including its unique ID in the url), further nouns MAY be in the singular. For example:

GET /people/{personId}/primaryRole

In this case “primaryRole” is written in its singular form, as there can only be one primary role and the resource name indicates that there can only be one of that resource.

All resource names MUST be in US/American English.

Avoiding actions in resource names

The action being performed on the resource MUST be expressed only via the HTTP verb. The action being performed SHOULD NOT be in the URL.

For example, to convert a geographic location to a street address (reverse geocoding a latitude and longitude), you would GET an address resource that matches the location attributes rather than pass the location to a reverse geocoding service. To illustrate:

GET /reverseGeocode?latitude=a&longitude=b (wrong)

GET /addresses?q=latitude==a;longitude==b (correct)

This returns a result (address resources) that contains the address(es) that match all of the specified attributes (latitude and longitude).