Understanding HTTP Methods for Backend APIs

When working with a backend API, an HTTP method communicates what a request is trying to do. I think of methods as verbs between a client and a server.

If the server were a library:

• GET asks to see a book;
• POST submits a new book;
• PUT replaces a book;
• PATCH changes part of a book;
• DELETE removes a book.

This article is a learning note about those common methods, not a complete REST API specification.

Safety and Idempotency

Two terms help explain why method choice matters:

• A safe method has read-only semantics. The client is not asking the server to change resource state.
• An idempotent method has the same intended server effect when the same request is repeated.

Safe semantics do not mean the server performs no side effects at all. It may still write access logs or metrics; the important part is that the client did not request a state change.

Idempotent describes the intended effect, not an identical response. Repeating a successful DELETE may return a different status after the resource is already gone while its intended state remains deleted.

GET: Read Data

Use GET when the client asks for a representation without requesting a state change:

GET /api/users/123
GET /api/products?search=laptop&page=2

Query parameters are visible in URLs and can appear in browser history, proxy logs, or server logs. Passwords and access tokens do not belong there.

GET responses can be cached when the response headers and surrounding HTTP rules allow it.

POST: Submit Data

POST sends data to a resource for processing. Creating a new resource is a common use:

POST /api/users
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com"
}

Repeating the request may create another user, so POST is not idempotent by default. Workflows that must tolerate retries need an API contract that can recognize duplicate submissions.

When a resource is created, 201 Created is a common response. The exact response still depends on the API contract.

PUT: Replace the Target Resource

PUT usually sends the representation that should become the state of the target resource:

PUT /api/users/123
Content-Type: application/json

{
  "name": "John Smith",
  "email": "john.smith@example.com",
  "city": "Jakarta"
}

PUT is idempotent: sending the same replacement again has the same intended effect. Whether an omitted application field is removed, reset, or rejected must be defined by the API rather than guessed by the client.

PATCH: Change Part of a Resource

PATCH applies a partial modification:

PATCH /api/users/123
Content-Type: application/json

{
  "email": "newemail@example.com"
}

Fields outside the requested modification can remain unchanged. PATCH is not idempotent by definition, although a particular patch format and operation can be designed to be idempotent. The API should document the patch format and how concurrent updates are handled.

DELETE: Remove a Resource

DELETE /api/users/123

DELETE is idempotent in its intended effect: after one or several successful requests, the target resource remains removed. A successful API might return 204 No Content, 200 OK, or 202 Accepted, depending on whether deletion is complete and whether a response representation is returned.

Soft deletion, authorization, and behavior for an already missing resource are application decisions that should be explicit in the API contract.

Keep Resource URLs Predictable

Methods make action names in resource URLs unnecessary for common CRUD operations:

GET    /api/users
GET    /api/users/123
POST   /api/users
PUT    /api/users/123
PATCH  /api/users/123
DELETE /api/users/123

This is generally clearer than mixing styles such as /getUsers, /user-create, and /deleteUser. Not every operation is CRUD, so an API can still model domain actions when a resource-oriented representation is clearer.

A Few Common Response Codes

Method and status code are related, but there is no fixed status code for every method:

The API contract should explain which responses a client can expect for each operation.

What I Keep in Mind

• Use GET for read-only requests.
• Do not use POST for every operation merely because it accepts a body.
• Treat PUT as a replacement unless the API defines otherwise.
• Document the patch format and behavior of PATCH.
• Remember that idempotent does not mean every retry is automatically safe in the presence of authorization, concurrency, or other side effects.
• Keep resource naming and error responses consistent within one API.

Choosing the method according to its semantics makes an endpoint easier to understand without turning every API into the same design.

References

• RFC 9110: HTTP Semantics
• RFC 5789: PATCH Method for HTTP
• MDN: HTTP request methods