Skip to content

RESTful URI naming conventions

In a RESTful architecture, every URI represents a specific resource^[600-developer__principle__restful-rule.md]. Consequently, URIs should contain only nouns, avoiding verbs^[600-developer__principle__restful-rule.md]. The nouns used typically correspond to database table names and should be pluralized, as they generally represent a "collection" of records^[600-developer__principle__restful-rule.md]. A common design error to avoid is embedding verbs within the URI path, such as using /transfer in a URL^[600-developer__principle__restful-rule.md].

Resource Identification

Clients interact with the server to transfer a representation of a resource^[600-developer__principle__restful-rule.md]. The system manipulates resource states (Representational State Transfer) through four standard HTTP verbs^[600-developer__principle__restful-rule.md].

URI Structure Examples

  • GET /zoos: Lists all zoos^[600-developer__principle__restful-rule.md].
  • POST /zoos: Creates a new zoo^[600-developer__principle__restful-rule.md].
  • GET /zoos/ID: Retrieves a specific zoo^[600-developer__principle__restful-rule.md].
  • PUT /zoos/ID: Updates a specific zoo (requires full resource data)^[600-developer__principle__restful-rule.md].
  • PATCH /zoos/ID: Updates a specific zoo (requires partial data)^[600-developer__principle__restful-rule.md].
  • DELETE /zoos/ID: Deletes a specific zoo^[600-developer__principle__restful-rule.md].
  • GET /zoos/ID/animals: Lists all animals within a specific zoo^[600-developer__principle__restful-rule.md].

HTTP methods (Verbs)

The action performed on a resource is determined solely by the HTTP method, not the URI^[600-developer__principle__restful-rule.md].

Common Methods and Idempotency

  • GET (SELECT): Retrieves one or more resources from the server^[600-developer__principle__restful-rule.md]. This request is idempotent, meaning multiple identical requests yield the same result and do not alter the server state^[600-developer__principle__restful-rule.md].
  • POST (CREATE): Creates a new resource on the server^[600-developer__principle__restful-rule.md]. This request is non-idempotent, as sending it multiple times will result in creating multiple resources^[600-developer__principle__restful-rule.md].
  • PUT (UPDATE): Updates an existing resource on the server using the complete resource data provided by the client^[600-developer__principle__restful-rule.md]. This request is idempotent^[600-developer__principle__restful-rule.md].
  • PATCH (UPDATE): Updates an existing resource, but only with the specific changed attributes provided by the client^[600-developer__principle__restful-rule.md].
  • DELETE (DELETE): Removes a resource from the server^[600-developer__principle__restful-rule.md]. This request is idempotent, as deleting an already-deleted resource results in the same state^[600-developer__principle__restful-rule.md].
  • HEAD: Retrieves HTTP headers and status codes for a resource without returning the body; useful for checking availability^[600-developer__principle__restful-rule.md].

Response Formats

The structure of the response body typically varies based on the HTTP method used^[600-developer__principle__restful-rule.md].

  • GET /collection: Returns a list (array) of resource objects^[600-developer__principle__restful-rule.md].
  • GET /collection/resource: Returns a single resource object^[600-developer__principle__restful-rule.md].
  • POST /collection: Returns the newly generated resource object^[600-developer__principle__restful-rule.md].
  • PUT /collection/resource: Returns the complete resource object (post-update)^[600-developer__principle__restful-rule.md].
  • PATCH /collection/resource: Returns the complete resource object (post-update)^[600-developer__principle__restful-rule.md].
  • DELETE /collection/resource: Returns an empty document^[600-developer__principle__restful-rule.md].

Status Codes

Standard HTTP status codes indicate the outcome of the request^[600-developer__principle__restful-rule.md].

  • 200 OK: Successful retrieval of data (usually GET)^[600-developer__principle__restful-rule.md].
  • 201 CREATED: Successful creation or modification of data^[600-developer__principle__restful-rule.md].
  • 202 Accepted: The request has been accepted for background processing (asynchronous)^[600-developer__principle__restful-rule.md].
  • 204 NO CONTENT: Successful deletion, typically returning no body^[600-developer__principle__restful-rule.md].
  • 400 INVALID REQUEST: The request was malformed (e.g., validation error)^[600-developer__principle__restful-rule.md].
  • 401 Unauthorized: Authentication is missing or invalid^[600-developer__principle__restful-rule.md].
  • 403 Forbidden: The user is authenticated but lacks permission^[600-developer__principle__restful-rule.md].
  • 404 NOT FOUND: The requested resource does not exist^[600-developer__principle__restful-rule.md].
  • 422 Unprocesable entity: A validation error occurred during object creation^[600-developer__principle__restful-rule.md].
  • 500 INTERNAL SERVER ERROR: A server-side error occurred^[600-developer__principle__restful-rule.md].
  • [[API Design]]
  • [[HTTP]]

Sources

^[600-developer__principle__restful-rule.md]