Skip to content

HTTP method semantics in REST

In RESTful architecture, clients interact with server resources primarily through standard HTTP protocol semantics. These methods define the type of operation to be performed on the resource, facilitating "Representational State Transfer" (表现层状态转化).^[600-developer__principle__restful-rule.md]

Common HTTP methods

The core of RESTful interaction relies on five primary verbs (methods) that correspond to CRUD operations^[600-developer__principle__restful-rule.md].

  • GET (SELECT): Retrieves a resource (one or more items) 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, modified resource^[600-developer__principle__restful-rule.md].
  • PATCH (UPDATE): Updates an existing resource, but the client only needs to provide the specific properties 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 methods is idempotency, which determines whether making the same request multiple times has the same effect as making it once^[600-developer__principle__restful-rule.md].

  • Safe and Idempotent: GET requests do not modify server resources; retrieving data once or twice yields the same result^[600-developer__principle__restful-rule.md]. HEAD is similarly idempotent and is used to retrieve only HTTP headers and status codes without the body content^[600-developer__principle__restful-rule.md].
  • Idempotent: PUT and DELETE are idempotent. Deleting a resource once removes it; deleting it again leaves the server in the same state (resource not found)^[600-developer__principle__restful-rule.md]. Updating a resource with the same data multiple times results in the same final state^[600-developer__principle__restful-rule.md].
  • Non-Idempotent: POST is generally non-idempotent, as submitting the same request to create a new resource typically results in the creation of multiple distinct resources^[600-developer__principle__restful-rule.md].

Common Design Error: Verbs in URI

A fundamental principle of RESTful design is that the URI should represent a resource (a noun), not an action^[600-developer__principle__restful-rule.md]. Resources are typically represented as collections (plural nouns), often corresponding to database table names^[600-developer__principle__restful-rule.md].

Consequently, URIs should not contain verbs. The action is determined solely by the HTTP method^[600-developer__principle__restful-rule.md].

  • Incorrect: POST /accounts/1/transfer/500/to/2 (Contains the verb "transfer")^[600-developer__principle__restful-rule.md]
  • Correct: POST /accounts/1/transaction/500/to/2 (Focuses on the resource "transaction")^[600-developer__principle__restful-rule.md]

Sources

  • 600-developer__principle__restful-rule.md