Skip to content

RESTful API URL Design Principles

RESTful API URL Design Principles are conventions for structuring web APIs to align with the architecture of REST (Representational State Transfer). In this context, every URL represents a specific resource, and the interaction with that resource is defined by the HTTP protocol.^[600-developer-principle-restful-rule.md]

Core Concepts

The fundamental rule of RESTful URL design is that URLs should contain only nouns, not verbs.^[600-developer-principle-restful-rule.md] Since a URL represents a resource—often corresponding to a database table or collection—it should be treated as a noun.^[600-developer-principle-restful-rule.md] Additionally, because database tables are collections of records, API nouns should generally be used in their plural form (e.g., /users rather than /user).^[600-developer-principle-restful-rule.md]

A common design error to avoid is including verbs in the URI, such as /accounts/1/transfer/500/to/2.^[600-developer-principle-restful-rule.md] Instead, actions should be represented by the appropriate HTTP verb on a noun-based resource (e.g., /accounts/1/transactions).^[600-developer-principle-restful-rule.md]

HTTP methods and Semantics

Clients interact with server resources using standard HTTP verbs (methods) to perform Create, Read, Update, and Delete (CRUD) operations.^[600-developer-principle-restful-rule.md] The specific behavior is defined by the combination of the URL and the HTTP method.

Common Verbs and SQL Mapping

^[600-developer-principle-restful-rule.md] * GET (SELECT): Retrieves a resource (one or many) from the server. * POST (CREATE): Creates a new resource on the server. * PUT (UPDATE): Updates a resource on the server (requires the complete resource data). * PATCH (UPDATE): Updates a resource on the server (requires only the changed properties). * DELETE (DELETE): Removes a resource from the server.

Idempotency and Safety

  • GET: Requests are idempotent and safe; sending a request once or multiple times yields the same result and does not change the server state.^[600-developer-principle-restful-rule.md]
  • PUT: Requests are idempotent; sending the same update request multiple times results in the same final state.^[600-developer-principle-restful-rule.md]
  • DELETE: Requests are idempotent; deleting a resource once or multiple times yields the same result (the resource is gone).^[600-developer-principle-restful-rule.md]
  • POST: Requests are non-idempotent; sending a POST request multiple times typically creates multiple resources.^[600-developer-principle-restful-rule.md]
  • HEAD: Retrieves only HTTP headers and status codes, not the resource body.^[600-developer-principle-restful-rule.md]

URL Structure Examples

URLs should be hierarchical, reflecting the relationship between resources.^[600-developer-principle-restful-rule.md]

  • List Collection: GET /zoos (List all zoos)
  • Get Specific Item: GET /zoos/ID (Get a specific zoo)
  • Create Item: POST /zoos (Create a new zoo)
  • Update Item: PUT /zoos/ID or PATCH /zoos/ID
  • Delete Item: DELETE /zoos/ID
  • Sub-resources: GET /zoos/ID/animals (List animals for a specific zoo)
  • Nested Operations: DELETE /zoos/ID/animals/ID (Delete a specific animal in a specific zoo)

^[600-developer-principle-restful-rule.md]

Response Codes and Return Values

APIs should return standard HTTP status codes to indicate the success or failure of a request.^[600-developer-principle-restful-rule.md]

  • 200 OK: Request succeeded (e.g., GET).^[600-developer-principle-restful-rule.md]
  • 201 Created: Resource successfully created (e.g., POST).^[600-developer-principle-restful-rule.md]
  • 204 No Content: Request succeeded but returns no body (e.g., DELETE).^[600-developer-principle-restful-rule.md]
  • 400 Bad Request: Invalid request syntax or parameters.^[600-developer-principle-restful-rule.md]
  • 401 Unauthorized: Authentication failed or missing.^[600-developer-principle-restful-rule.md]
  • 404 Not Found: Requested resource does not exist.^[600-developer-principle-restful-rule.md]
  • 500 Internal Server Error: Server-side error occurred.^[600-developer-principle-restful-rule.md]

The structure of the response body typically corresponds to the request type: ^[600-developer-principle-restful-rule.md] * GET /collection: Returns a list (array) of resource objects. * GET /collection/resource: Returns a single resource object. * POST /collection: Returns the newly generated resource object. * PUT /collection/resource: Returns the complete modified resource object. * DELETE /collection/resource: Returns an empty document.

Sources

^[600-developer-principle-restful-rule.md]