Skip to content

HTTP Verb Semantics in REST

In RESTful architecture, HTTP verbs (methods) define the semantic operations performed on resources. Each URI represents a resource (usually a noun, often pluralized to match database collections), and the interaction between client and server—transferring representations of these resources—is achieved through these verbs^[600-developer-principle-restful-rule.md].

Core Semantics

The five primary HTTP verbs used in REST correspond to Create, Read, Update, and Delete (CRUD) operations^[600-developer-principle-restful-rule.md]:

  • GET (SELECT): Retrieves one or more resources from the server^[600-developer-principle-restful-rule.md].
  • POST (CREATE): Creates a new resource on the server^[600-developer-principle-restful-rule.md].
  • PUT (UPDATE): Updates an existing resource on the server, requiring the client to provide the complete, changed resource^[600-developer-principle-restful-rule.md].
  • PATCH (UPDATE): Updates an existing resource, but only requires the client to provide the specific attributes that have changed^[600-developer-principle-restful-rule.md].
  • DELETE (DELETE): Removes a resource from the server^[600-developer-principle-restful-rule.md].

Idempotency and Safety

A key distinction between these verbs is idempotency, which determines whether making the same request multiple times results in the same server state^[600-developer-principle-restful-rule.md].

  • Safe and Idempotent: GET requests do not alter server resources; sending a request once or twice yields the same result^[600-developer-principle-restful-rule.md].
  • Idempotent: PUT and DELETE requests change the resource state, but making the identical request repeatedly results in the same final state^[600-developer-principle-restful-rule.md].
  • Non-Idempotent: POST requests create new resources. Sending the same POST request multiple times typically results in the creation of multiple distinct resources^[600-developer-principle-restful-rule.md].
  • Metadata: HEAD is used to retrieve HTTP status codes and headers without the actual resource body; this method is also idempotent^[600-developer-principle-restful-rule.md].

URI Conventions

A common design error is including verbs in the URI path^[600-developer-principle-restful-rule.md]. URIs should contain only nouns (representing resources).

  • Incorrect: POST /accounts/1/transfer/500/to/2^[600-developer-principle-restful-rule.md]
  • Correct: POST /accounts/1/transaction/500/to/2^[600-developer-principle-restful-rule.md]

Response Codes and Return Values

Successful operations return specific status codes and body structures^[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 updated resource object^[600-developer-principle-restful-rule.md].
  • PATCH /collection/resource: Returns the complete updated resource object^[600-developer-principle-restful-rule.md].
  • DELETE /collection/resource: Returns an empty document^[600-developer-principle-restful-rule.md].

Common Status Codes

Standard HTTP status codes indicate the outcome of an operation^[600-developer-principle-restful-rule.md]:

  • 200 OK: Successful return of requested data (typically for GET)^[600-developer-principle-restful-rule.md].
  • 201 CREATED: Successful creation or modification of data (POST/PUT/PATCH)^[600-developer-principle-restful-rule.md].
  • 204 NO CONTENT: Successful deletion (DELETE)^[600-developer-principle-restful-rule.md].
  • 400 INVALID REQUEST: The request was malformed (e.g., validation errors)^[600-developer-principle-restful-rule.md].
  • [[REST]]
  • [[API Design]]
  • [[CRUD]]

Sources

  • 600-developer-principle-restful-rule.md