RESTful API Design - Learning Module

Loading content...

0/246

HTTP Methods and Semantics

Methods as the Verbs of REST

If resources are the nouns of REST, HTTP methods are the verbs. While resources identify what you're interacting with, HTTP methods express what action you want to perform. This separation is fundamental to REST's uniform interface—rather than defining custom operations for every resource, we use a standard set of methods with well-defined semantics.

Understanding HTTP method semantics isn't just about knowing that GET retrieves and DELETE removes. It's about understanding the contracts these methods provide: Which methods are safe to retry? Which can be cached? Which might change server state? These semantics enable infrastructure like caches, load balancers, and proxies to make intelligent decisions without understanding your specific API.

In this page, we'll explore each HTTP method in depth—its purpose, its guarantees, its proper usage, and the common mistakes developers make. Mastering method semantics is essential for building APIs that behave predictably and integrate well with the broader HTTP ecosystem.

What You Will Learn

By the end of this page, you will understand the semantics of each HTTP method—GET, POST, PUT, PATCH, DELETE, and others. You'll know which methods are safe, which are idempotent, and how these properties affect caching, retries, and error handling. You'll be able to select the correct method for any operation and explain why.

Method Semantics Overview

HTTP defines a set of methods (sometimes called "verbs") that indicate the desired action to be performed on a resource. Each method has specific semantic properties that determine how it should behave and how clients and intermediaries can interact with it.

Two Critical Properties

Every HTTP method is characterized by two important properties:

1. Safety

A method is safe if it doesn't modify resource state. Safe methods are for retrieval and inspection—they have no side effects. Clients can call safe methods without worrying about unintended changes.

Safe methods: GET, HEAD, OPTIONS, TRACE

2. Idempotency

A method is idempotent if making the same request multiple times produces the same result as making it once. The server state after N identical requests is the same as after 1 request. This property enables safe retries.

Idempotent methods: GET, HEAD, OPTIONS, TRACE, PUT, DELETE

Non-idempotent method: POST, PATCH (typically)

HTTP Method Properties Matrix
Method	Safe	Idempotent	Request Body	Response Body	Typical Use
GET	✅ Yes	✅ Yes	No	Yes	Retrieve resource representation
HEAD	✅ Yes	✅ Yes	No	No	Get headers only
OPTIONS	✅ Yes	✅ Yes	Optional	Yes	Get allowed methods
POST	❌ No	❌ No	Yes	Yes	Create resource / trigger action
PUT	❌ No	✅ Yes	Yes	Optional	Replace resource entirely
PATCH	❌ No	Varies*	Yes	Optional	Partial update
DELETE	❌ No	✅ Yes	Optional	Optional	Remove resource

PATCH and Idempotency

PATCH is not inherently idempotent—it depends on how it's implemented. A PATCH that says 'set name to X' is idempotent. A PATCH that says 'increment counter by 1' is not. Design your PATCH operations to be idempotent when possible.

GET - Retrieving Resources

GET is the most common HTTP method. It retrieves a representation of the specified resource without modifying server state.

Semantics

Safe: GET must not change resource state
Idempotent: Multiple identical GET requests produce the same result
Cacheable: Responses are cacheable by default
No request body: GET requests should not include a body (some servers ignore it)

Proper Usage

GET /users                    # Retrieve collection of users
GET /users/123                # Retrieve specific user
GET /users/123/orders         # Retrieve user's orders
GET /users?status=active      # Retrieve filtered collection
GET /products?q=laptop        # Search products

Response Expectations

200 OK: Resource found, representation returned in body
404 Not Found: Resource doesn't exist
304 Not Modified: Resource unchanged (with caching headers)
400 Bad Request: Invalid query parameters

GET Request/Response Examples
HTTP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# Request: Get a specific user
GET /api/v1/users/123 HTTP/1.1
Host: api.example.com
Accept: application/json
 
# Response: User found
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=3600
ETag: "abc123"
 
{
    "id": 123,
    "name": "Alice Thompson",
    "email": "alice@example.com",
    "createdAt": "2024-01-15T10:30:00Z",
    "links": {
        "self": "/users/123",
        "orders": "/users/123/orders"
    }
}
 
# Conditional request (with caching)
GET /api/v1/users/123 HTTP/1.1
Host: api.example.com
Accept: application/json
If-None-Match: "abc123"
 
# Response: Not modified (use cached version)
HTTP/1.1 304 Not Modified
ETag: "abc123"

Never Use GET to Modify State

A common anti-pattern is using GET for actions: GET /users/123/delete. This violates GET's safety guarantee, breaks caching, and allows unintended actions from crawlers, prefetching, or browser history. State-changing operations must use POST, PUT, PATCH, or DELETE.

GET for Collections

When GETting a collection, include pagination and filtering capabilities:

GET /users?page=2&per_page=20&sort=created_at&order=desc

Response should include:

The collection items
Pagination metadata (total count, current page, links to next/prev)
Applied filters (so clients know what they asked for)

POST - Creating Resources

POST submits data to be processed by the identified resource. Its most common use in REST APIs is creating new resources, but it also handles operations that don't fit other methods.

Semantics

Not safe: POST modifies server state
Not idempotent: Multiple identical POST requests may create multiple resources
Not cacheable: Unless response headers explicitly allow it
Request body required: Contains the data to process

Proper Usage

POST /users                   # Create a new user
POST /orders                  # Create a new order
POST /users/123/orders        # Create order for user 123
POST /emails/456/send         # Trigger sending (action)
POST /reports/generate        # Trigger report generation

Response Expectations

201 Created: Resource successfully created
- Include Location header with URI of new resource
- Include the created resource in response body
200 OK: Processing succeeded (for non-create operations)
202 Accepted: Request accepted for asynchronous processing
400 Bad Request: Invalid input data
409 Conflict: Resource already exists or constraint violation

POST Request/Response Examples
HTTP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
# Request: Create a new user
POST /api/v1/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json
 
{
    "name": "Bob Wilson",
    "email": "bob@example.com",
    "role": "developer"
}
 
# Response: User created
HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/users/456
 
{
    "id": 456,
    "name": "Bob Wilson",
    "email": "bob@example.com",
    "role": "developer",
    "createdAt": "2024-06-15T14:30:00Z",
    "links": {
        "self": "/users/456",
        "orders": "/users/456/orders"
    }
}
 
# Asynchronous operation
POST /api/v1/reports/generate HTTP/1.1
Host: api.example.com
Content-Type: application/json
 
{
    "type": "sales",
    "dateRange": {"start": "2024-01-01", "end": "2024-06-30"}
}
 
# Response: Accepted for processing
HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /api/v1/reports/jobs/789
 
{
    "jobId": "789",
    "status": "processing",
    "estimatedCompletionTime": "2024-06-15T14:35:00Z",
    "statusUrl": "/reports/jobs/789"
}

Why POST Is Non-Idempotent

Consider creating an order:

POST /orders
{"product": "laptop", "quantity": 1}

If this request is sent twice (perhaps due to network retry), two separate orders are created. This is correct behavior—POST is intentionally non-idempotent. To make creation idempotent, use a client-generated ID:

PUT /orders/client-generated-uuid
{"product": "laptop", "quantity": 1}

Or include an idempotency key in headers:

POST /orders
Idempotency-Key: unique-request-id-12345
{"product": "laptop", "quantity": 1}

The Location Header

When POST creates a resource, always include a Location header pointing to the new resource's URI. This allows clients to immediately access or reference the created resource without parsing the response body.

PUT - Replacing Resources

PUT replaces the entire resource at the specified URI with the provided representation. If the resource doesn't exist, PUT creates it (when the server supports this).

Semantics

Not safe: PUT modifies server state
Idempotent: Multiple identical PUT requests produce the same result
Request body required: Contains the complete new representation
The URI identifies the resource: The client specifies where the resource lives

Proper Usage

PUT /users/123                # Replace user 123 entirely
PUT /articles/my-article      # Create or replace article
PUT /config/settings          # Replace entire configuration

Response Expectations

200 OK: Resource updated, new representation in body
201 Created: Resource created (didn't exist before)
204 No Content: Resource updated, no body returned
404 Not Found: Resource doesn't exist (if creation not supported)
409 Conflict: Concurrent modification conflict

PUT Request/Response Examples
HTTP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
# Request: Replace a user entirely
PUT /api/v1/users/123 HTTP/1.1
Host: api.example.com
Content-Type: application/json
 
{
    "name": "Alice Thompson-Martinez",
    "email": "alice.m@example.com",
    "role": "senior-developer",
    "department": "engineering"
}
 
# Response: User replaced
HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "id": 123,
    "name": "Alice Thompson-Martinez",
    "email": "alice.m@example.com",
    "role": "senior-developer",
    "department": "engineering",
    "updatedAt": "2024-06-15T15:30:00Z"
}
 
# PUT with conditional update (optimistic locking)
PUT /api/v1/users/123 HTTP/1.1
Host: api.example.com
Content-Type: application/json
If-Match: "etag-abc123"
 
{
    "name": "Alice Updated",
    "email": "alice@example.com"
}
 
# Response: Conflict (someone else modified it)
HTTP/1.1 412 Precondition Failed
Content-Type: application/json
 
{
    "error": "Resource was modified by another request",
    "currentETag": "etag-xyz789"
}

PUT Replaces Everything

PUT is a full replacement. If the user has fields name, email, and role, and you PUT with only name and email, the role field will be removed (or reset to default). For partial updates, use PATCH instead.

PUT: Full Replacement

•Send complete resource representation
•Missing fields are removed/reset
•Idempotent by nature
•Client knows full state sent
•Simpler conflict resolution

PATCH: Partial Update

•Send only fields to change
•Unmentioned fields unchanged
•Can be idempotent (if designed well)
•More efficient for single-field changes
•More complex merge semantics

PATCH - Partial Updates

PATCH applies partial modifications to a resource. Unlike PUT, which replaces the entire resource, PATCH updates only the specified fields.

Semantics

Not safe: PATCH modifies server state
Not inherently idempotent: Depends on patch operations (see below)
Request body required: Contains the changes to apply
Flexible format: Can use various patch document formats

Proper Usage

PATCH /users/123              # Update specific fields of user
PATCH /orders/456/status      # Update order status only
PATCH /articles/789           # Update article metadata

Patch Document Formats

There are multiple ways to specify patches:

1. Merge Patch (RFC 7396) — Most common and intuitive

{"name": "New Name", "email": "new@example.com"}

Content-Type: application/merge-patch+json

2. JSON Patch (RFC 6902) — More powerful, explicit operations

[
  {"op": "replace", "path": "/name", "value": "New Name"},
  {"op": "add", "path": "/tags/-", "value": "new-tag"}
]

Content-Type: application/json-patch+json

PATCH Request/Response Examples
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
# Merge Patch: Simple field updates
PATCH /api/v1/users/123 HTTP/1.1
Host: api.example.com
Content-Type: application/merge-patch+json
 
{
    "email": "alice.new@example.com",
    "role": "tech-lead"
}
 
# Response
HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "id": 123,
    "name": "Alice Thompson",
    "email": "alice.new@example.com",
    "role": "tech-lead",
    "department": "engineering",
    "updatedAt": "2024-06-15T16:00:00Z"
}
 
# Setting a field to null (removes it)
PATCH /api/v1/users/123 HTTP/1.1
Content-Type: application/merge-patch+json
 
{
    "nickname": null
}

Making PATCH Idempotent

PATCH can be non-idempotent. Consider:

{"views": {"$increment": 1}}

Calling this twice increments views twice—not idempotent.

To ensure idempotency:

Use absolute values, not relative: {"views": 150} instead of {"$increment": 1}
Implement client-supplied idempotency keys
Use test operations in JSON Patch to verify initial state

When to Use PATCH vs. PUT

Use PUT when the client has the complete resource and wants to replace it entirely. Use PATCH when the client wants to modify specific fields without affecting others. Most user-facing updates (changing email, updating profile) are better as PATCH because they avoid accidentally clearing unrelated fields.

DELETE - Removing Resources

DELETE removes the specified resource from the server.

Semantics

Not safe: DELETE modifies server state
Idempotent: Deleting an already-deleted resource has no additional effect
Request body optional: Rarely used, some servers ignore it
Response body optional: Often 204 No Content

Proper Usage

DELETE /users/123             # Delete user 123
DELETE /orders/456/items/789  # Delete item from order
DELETE /sessions/current      # Log out (delete current session)

Response Expectations

200 OK: Deleted, response body contains deleted resource or confirmation
204 No Content: Deleted, no response body
202 Accepted: Deletion queued for asynchronous processing
404 Not Found: Resource doesn't exist (can also return 204 for idempotency)
409 Conflict: Cannot delete due to dependencies

DELETE Request/Response Examples
HTTP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# Simple delete
DELETE /api/v1/users/123 HTTP/1.1
Host: api.example.com
 
# Response: No Content
HTTP/1.1 204 No Content
 
# Delete with confirmation in response
DELETE /api/v1/users/123 HTTP/1.1
Host: api.example.com
Accept: application/json
 
# Response: Deleted resource returned
HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "id": 123,
    "name": "Alice Thompson",
    "deletedAt": "2024-06-15T16:30:00Z",
    "message": "User successfully deleted"
}
 
# Idempotent delete (second request for same resource)
DELETE /api/v1/users/123 HTTP/1.1
Host: api.example.com
 
# Option 1: Return 404 (not found)
HTTP/1.1 404 Not Found
 
# Option 2: Return 204 (idempotent - already deleted)
HTTP/1.1 204 No Content

Soft Delete vs. Hard Delete

Real-world APIs often implement soft delete (marking as deleted) rather than hard delete (actual removal):

Hard Delete:

Resource is permanently removed
Subsequent GET returns 404
Cannot be recovered

Soft Delete:

Resource is marked with deletedAt timestamp
Resource may still be accessible via special queries
Can be recovered (undeleted)
Better for audit trails and data recovery

# Soft delete - mark as deleted
DELETE /users/123  →  Sets deletedAt: "2024-06-15T16:30:00Z"

# Get deleted user (if API supports it)
GET /users/123?includeSoftDeleted=true

# Restore (undelete)
POST /users/123/restore  or  PATCH /users/123 {deletedAt: null}

Cascade Deletes

When a parent resource has children, decide what happens on delete: cascade (delete children too), restrict (prevent delete if children exist), or orphan (leave children). Document this behavior clearly—unexpected cascading deletes are a common cause of data loss.

Other HTTP Methods

While GET, POST, PUT, PATCH, and DELETE cover most API operations, other HTTP methods are useful in specific scenarios.

HEAD

HEAD is identical to GET but returns only headers, no body. Use it to:

Check if a resource exists without downloading it
Get metadata (Content-Length, Last-Modified, ETag)
Validate cache freshness

HEAD /files/large-report.pdf
→ Returns Content-Length: 15000000, but no body

OPTIONS

OPTIONS returns the allowed methods for a resource. It's crucial for CORS preflight requests:

OPTIONS /users/123
→ Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
→ Access-Control-Allow-Methods: GET, PUT, PATCH, DELETE

TRACE

TRACE echoes the received request back to the client. Useful for debugging proxy chains, but typically disabled for security reasons.

Complete HTTP Method Reference
Method	Purpose	Safe	Idempotent	Common Use Case
GET	Retrieve resource	✅	✅	Fetch data
HEAD	Get headers only	✅	✅	Check existence, metadata
OPTIONS	Get allowed methods	✅	✅	CORS preflight
TRACE	Loop-back test	✅	✅	Debug (usually disabled)
POST	Submit data / create	❌	❌	Create resources, actions
PUT	Replace resource	❌	✅	Full update
PATCH	Partial update	❌	Varies	Partial update
DELETE	Remove resource	❌	✅	Delete resources
CONNECT	Establish tunnel	❌	❌	Proxy tunneling (HTTPS)

Method Override for Limited Clients

Some clients (older browsers, proxies) only support GET and POST. APIs sometimes accept X-HTTP-Method-Override header or _method query parameter to tunnel other methods through POST. Example: POST /users/123?_method=DELETE or POST with header X-HTTP-Method-Override: DELETE.

Method Selection Guide

Choosing the right HTTP method depends on what you're trying to accomplish. Use this decision guide:

Converting Mermaid diagram...

Common Operations and Methods
Operation	Method	URI Pattern	Notes
List all resources	GET	`/resources`	With pagination
Get single resource	GET	`/resources/{id}`
Search/filter resources	GET	`/resources?query=x`	Query parameters
Create resource (server ID)	POST	`/resources`	Return 201 + Location
Create resource (client ID)	PUT	`/resources/{id}`	Idempotent creation
Replace resource entirely	PUT	`/resources/{id}`	All fields required
Update specific fields	PATCH	`/resources/{id}`	Only changed fields
Delete resource	DELETE	`/resources/{id}`	Return 204 or 200
Trigger action	POST	`/resources/{id}/action`	Non-CRUD operations
Check existence	HEAD	`/resources/{id}`	No body returned

Summary: HTTP Methods and Semantics

HTTP methods provide a standard vocabulary for resource operations. Understanding their semantics is essential for building predictable, scalable APIs.

Key Takeaways

•GET is safe and idempotent — Never modify state with GET; responses are cacheable by default
•POST creates resources and triggers actions — Non-idempotent; use for server-generated IDs
•PUT replaces resources entirely — Idempotent; all fields must be provided
•PATCH updates specific fields — Design for idempotency; use Merge Patch or JSON Patch
•DELETE removes resources — Idempotent; consider soft delete for data recovery
•Safety enables caching; idempotency enables retries — These properties guide infrastructure behavior
•Method semantics are contracts — Clients, proxies, and caches rely on these guarantees
•Choose methods based on semantics, not convention — Each method has specific meaning

What's next:

We've covered resources (nouns) and methods (verbs). The final piece is Status Codes and Responses—how your API communicates the outcome of each operation. Proper status codes make APIs debuggable, automatable, and developer-friendly.

Page Complete

You now understand HTTP method semantics deeply—not just what each method does, but what guarantees it provides. This knowledge enables you to select the right method for every operation and build APIs that work correctly with caches, proxies, and retry logic.

HTTP Methods and Semantics

Methods as the Verbs of REST

What You Will Learn

Method Semantics Overview

Two Critical Properties

Every HTTP method is characterized by two important properties:

1. Safety

Safe methods: GET, HEAD, OPTIONS, TRACE

2. Idempotency

Idempotent methods: GET, HEAD, OPTIONS, TRACE, PUT, DELETE

Non-idempotent method: POST, PATCH (typically)

HTTP Method Properties Matrix
Method	Safe	Idempotent	Request Body	Response Body	Typical Use
GET	✅ Yes	✅ Yes	No	Yes	Retrieve resource representation
HEAD	✅ Yes	✅ Yes	No	No	Get headers only
OPTIONS	✅ Yes	✅ Yes	Optional	Yes	Get allowed methods
POST	❌ No	❌ No	Yes	Yes	Create resource / trigger action
PUT	❌ No	✅ Yes	Yes	Optional	Replace resource entirely
PATCH	❌ No	Varies*	Yes	Optional	Partial update
DELETE	❌ No	✅ Yes	Optional	Optional	Remove resource

PATCH and Idempotency

GET - Retrieving Resources

GET is the most common HTTP method. It retrieves a representation of the specified resource without modifying server state.

Semantics

Safe: GET must not change resource state
Idempotent: Multiple identical GET requests produce the same result
Cacheable: Responses are cacheable by default
No request body: GET requests should not include a body (some servers ignore it)

Proper Usage

GET /users                    # Retrieve collection of users
GET /users/123                # Retrieve specific user
GET /users/123/orders         # Retrieve user's orders
GET /users?status=active      # Retrieve filtered collection
GET /products?q=laptop        # Search products

Response Expectations

200 OK: Resource found, representation returned in body
404 Not Found: Resource doesn't exist
304 Not Modified: Resource unchanged (with caching headers)
400 Bad Request: Invalid query parameters

GET Request/Response Examples
HTTP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# Request: Get a specific user
GET /api/v1/users/123 HTTP/1.1
Host: api.example.com
Accept: application/json
 
# Response: User found
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=3600
ETag: "abc123"
 
{
    "id": 123,
    "name": "Alice Thompson",
    "email": "alice@example.com",
    "createdAt": "2024-01-15T10:30:00Z",
    "links": {
        "self": "/users/123",
        "orders": "/users/123/orders"
    }
}
 
# Conditional request (with caching)
GET /api/v1/users/123 HTTP/1.1
Host: api.example.com
Accept: application/json
If-None-Match: "abc123"
 
# Response: Not modified (use cached version)
HTTP/1.1 304 Not Modified
ETag: "abc123"

Never Use GET to Modify State

GET for Collections

When GETting a collection, include pagination and filtering capabilities:

GET /users?page=2&per_page=20&sort=created_at&order=desc

Response should include:

The collection items
Pagination metadata (total count, current page, links to next/prev)
Applied filters (so clients know what they asked for)

POST - Creating Resources

POST submits data to be processed by the identified resource. Its most common use in REST APIs is creating new resources, but it also handles operations that don't fit other methods.

Semantics

Not safe: POST modifies server state
Not idempotent: Multiple identical POST requests may create multiple resources
Not cacheable: Unless response headers explicitly allow it
Request body required: Contains the data to process

Proper Usage

POST /users                   # Create a new user
POST /orders                  # Create a new order
POST /users/123/orders        # Create order for user 123
POST /emails/456/send         # Trigger sending (action)
POST /reports/generate        # Trigger report generation

Response Expectations

201 Created: Resource successfully created
- Include Location header with URI of new resource
- Include the created resource in response body
200 OK: Processing succeeded (for non-create operations)
202 Accepted: Request accepted for asynchronous processing
400 Bad Request: Invalid input data
409 Conflict: Resource already exists or constraint violation

POST Request/Response Examples
HTTP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
# Request: Create a new user
POST /api/v1/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json
 
{
    "name": "Bob Wilson",
    "email": "bob@example.com",
    "role": "developer"
}
 
# Response: User created
HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/users/456
 
{
    "id": 456,
    "name": "Bob Wilson",
    "email": "bob@example.com",
    "role": "developer",
    "createdAt": "2024-06-15T14:30:00Z",
    "links": {
        "self": "/users/456",
        "orders": "/users/456/orders"
    }
}
 
# Asynchronous operation
POST /api/v1/reports/generate HTTP/1.1
Host: api.example.com
Content-Type: application/json
 
{
    "type": "sales",
    "dateRange": {"start": "2024-01-01", "end": "2024-06-30"}
}
 
# Response: Accepted for processing
HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /api/v1/reports/jobs/789
 
{
    "jobId": "789",
    "status": "processing",
    "estimatedCompletionTime": "2024-06-15T14:35:00Z",
    "statusUrl": "/reports/jobs/789"
}

Why POST Is Non-Idempotent

Consider creating an order:

POST /orders
{"product": "laptop", "quantity": 1}

PUT /orders/client-generated-uuid
{"product": "laptop", "quantity": 1}

Or include an idempotency key in headers:

POST /orders
Idempotency-Key: unique-request-id-12345
{"product": "laptop", "quantity": 1}

The Location Header

PUT - Replacing Resources

PUT replaces the entire resource at the specified URI with the provided representation. If the resource doesn't exist, PUT creates it (when the server supports this).

Semantics

Not safe: PUT modifies server state
Idempotent: Multiple identical PUT requests produce the same result
Request body required: Contains the complete new representation
The URI identifies the resource: The client specifies where the resource lives

Proper Usage

PUT /users/123                # Replace user 123 entirely
PUT /articles/my-article      # Create or replace article
PUT /config/settings          # Replace entire configuration

Response Expectations

200 OK: Resource updated, new representation in body
201 Created: Resource created (didn't exist before)
204 No Content: Resource updated, no body returned
404 Not Found: Resource doesn't exist (if creation not supported)
409 Conflict: Concurrent modification conflict

PUT Request/Response Examples
HTTP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
# Request: Replace a user entirely
PUT /api/v1/users/123 HTTP/1.1
Host: api.example.com
Content-Type: application/json
 
{
    "name": "Alice Thompson-Martinez",
    "email": "alice.m@example.com",
    "role": "senior-developer",
    "department": "engineering"
}
 
# Response: User replaced
HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "id": 123,
    "name": "Alice Thompson-Martinez",
    "email": "alice.m@example.com",
    "role": "senior-developer",
    "department": "engineering",
    "updatedAt": "2024-06-15T15:30:00Z"
}
 
# PUT with conditional update (optimistic locking)
PUT /api/v1/users/123 HTTP/1.1
Host: api.example.com
Content-Type: application/json
If-Match: "etag-abc123"
 
{
    "name": "Alice Updated",
    "email": "alice@example.com"
}
 
# Response: Conflict (someone else modified it)
HTTP/1.1 412 Precondition Failed
Content-Type: application/json
 
{
    "error": "Resource was modified by another request",
    "currentETag": "etag-xyz789"
}

PUT Replaces Everything

PUT: Full Replacement

•Send complete resource representation
•Missing fields are removed/reset
•Idempotent by nature
•Client knows full state sent
•Simpler conflict resolution

PATCH: Partial Update

•Send only fields to change
•Unmentioned fields unchanged
•Can be idempotent (if designed well)
•More efficient for single-field changes
•More complex merge semantics

PATCH - Partial Updates

PATCH applies partial modifications to a resource. Unlike PUT, which replaces the entire resource, PATCH updates only the specified fields.

Semantics

Not safe: PATCH modifies server state
Not inherently idempotent: Depends on patch operations (see below)
Request body required: Contains the changes to apply
Flexible format: Can use various patch document formats

Proper Usage

PATCH /users/123              # Update specific fields of user
PATCH /orders/456/status      # Update order status only
PATCH /articles/789           # Update article metadata

Patch Document Formats

There are multiple ways to specify patches:

1. Merge Patch (RFC 7396) — Most common and intuitive

{"name": "New Name", "email": "new@example.com"}

Content-Type: application/merge-patch+json

2. JSON Patch (RFC 6902) — More powerful, explicit operations

[
  {"op": "replace", "path": "/name", "value": "New Name"},
  {"op": "add", "path": "/tags/-", "value": "new-tag"}
]

Content-Type: application/json-patch+json

PATCH Request/Response Examples
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
# Merge Patch: Simple field updates
PATCH /api/v1/users/123 HTTP/1.1
Host: api.example.com
Content-Type: application/merge-patch+json
 
{
    "email": "alice.new@example.com",
    "role": "tech-lead"
}
 
# Response
HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "id": 123,
    "name": "Alice Thompson",
    "email": "alice.new@example.com",
    "role": "tech-lead",
    "department": "engineering",
    "updatedAt": "2024-06-15T16:00:00Z"
}
 
# Setting a field to null (removes it)
PATCH /api/v1/users/123 HTTP/1.1
Content-Type: application/merge-patch+json
 
{
    "nickname": null
}

Making PATCH Idempotent

PATCH can be non-idempotent. Consider:

{"views": {"$increment": 1}}

Calling this twice increments views twice—not idempotent.

To ensure idempotency:

Use absolute values, not relative: {"views": 150} instead of {"$increment": 1}
Implement client-supplied idempotency keys
Use test operations in JSON Patch to verify initial state

When to Use PATCH vs. PUT

DELETE - Removing Resources

DELETE removes the specified resource from the server.

Semantics

Not safe: DELETE modifies server state
Idempotent: Deleting an already-deleted resource has no additional effect
Request body optional: Rarely used, some servers ignore it
Response body optional: Often 204 No Content

Proper Usage

DELETE /users/123             # Delete user 123
DELETE /orders/456/items/789  # Delete item from order
DELETE /sessions/current      # Log out (delete current session)

Response Expectations

200 OK: Deleted, response body contains deleted resource or confirmation
204 No Content: Deleted, no response body
202 Accepted: Deletion queued for asynchronous processing
404 Not Found: Resource doesn't exist (can also return 204 for idempotency)
409 Conflict: Cannot delete due to dependencies

DELETE Request/Response Examples
HTTP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# Simple delete
DELETE /api/v1/users/123 HTTP/1.1
Host: api.example.com
 
# Response: No Content
HTTP/1.1 204 No Content
 
# Delete with confirmation in response
DELETE /api/v1/users/123 HTTP/1.1
Host: api.example.com
Accept: application/json
 
# Response: Deleted resource returned
HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "id": 123,
    "name": "Alice Thompson",
    "deletedAt": "2024-06-15T16:30:00Z",
    "message": "User successfully deleted"
}
 
# Idempotent delete (second request for same resource)
DELETE /api/v1/users/123 HTTP/1.1
Host: api.example.com
 
# Option 1: Return 404 (not found)
HTTP/1.1 404 Not Found
 
# Option 2: Return 204 (idempotent - already deleted)
HTTP/1.1 204 No Content

Soft Delete vs. Hard Delete

Real-world APIs often implement soft delete (marking as deleted) rather than hard delete (actual removal):

Hard Delete:

Resource is permanently removed
Subsequent GET returns 404
Cannot be recovered

Soft Delete:

Resource is marked with deletedAt timestamp
Resource may still be accessible via special queries
Can be recovered (undeleted)
Better for audit trails and data recovery

# Soft delete - mark as deleted
DELETE /users/123  →  Sets deletedAt: "2024-06-15T16:30:00Z"

# Get deleted user (if API supports it)
GET /users/123?includeSoftDeleted=true

# Restore (undelete)
POST /users/123/restore  or  PATCH /users/123 {deletedAt: null}

Cascade Deletes

Other HTTP Methods

While GET, POST, PUT, PATCH, and DELETE cover most API operations, other HTTP methods are useful in specific scenarios.

HEAD

HEAD is identical to GET but returns only headers, no body. Use it to:

Check if a resource exists without downloading it
Get metadata (Content-Length, Last-Modified, ETag)
Validate cache freshness

HEAD /files/large-report.pdf
→ Returns Content-Length: 15000000, but no body

OPTIONS

OPTIONS returns the allowed methods for a resource. It's crucial for CORS preflight requests:

OPTIONS /users/123
→ Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
→ Access-Control-Allow-Methods: GET, PUT, PATCH, DELETE

TRACE

TRACE echoes the received request back to the client. Useful for debugging proxy chains, but typically disabled for security reasons.

Complete HTTP Method Reference
Method	Purpose	Safe	Idempotent	Common Use Case
GET	Retrieve resource	✅	✅	Fetch data
HEAD	Get headers only	✅	✅	Check existence, metadata
OPTIONS	Get allowed methods	✅	✅	CORS preflight
TRACE	Loop-back test	✅	✅	Debug (usually disabled)
POST	Submit data / create	❌	❌	Create resources, actions
PUT	Replace resource	❌	✅	Full update
PATCH	Partial update	❌	Varies	Partial update
DELETE	Remove resource	❌	✅	Delete resources
CONNECT	Establish tunnel	❌	❌	Proxy tunneling (HTTPS)

Method Override for Limited Clients

Method Selection Guide

Choosing the right HTTP method depends on what you're trying to accomplish. Use this decision guide:

Converting Mermaid diagram...

Common Operations and Methods
Operation	Method	URI Pattern	Notes
List all resources	GET	`/resources`	With pagination
Get single resource	GET	`/resources/{id}`
Search/filter resources	GET	`/resources?query=x`	Query parameters
Create resource (server ID)	POST	`/resources`	Return 201 + Location
Create resource (client ID)	PUT	`/resources/{id}`	Idempotent creation
Replace resource entirely	PUT	`/resources/{id}`	All fields required
Update specific fields	PATCH	`/resources/{id}`	Only changed fields
Delete resource	DELETE	`/resources/{id}`	Return 204 or 200
Trigger action	POST	`/resources/{id}/action`	Non-CRUD operations
Check existence	HEAD	`/resources/{id}`	No body returned

Summary: HTTP Methods and Semantics

HTTP methods provide a standard vocabulary for resource operations. Understanding their semantics is essential for building predictable, scalable APIs.

Key Takeaways

•GET is safe and idempotent — Never modify state with GET; responses are cacheable by default
•POST creates resources and triggers actions — Non-idempotent; use for server-generated IDs
•PUT replaces resources entirely — Idempotent; all fields must be provided
•PATCH updates specific fields — Design for idempotency; use Merge Patch or JSON Patch
•DELETE removes resources — Idempotent; consider soft delete for data recovery
•Safety enables caching; idempotency enables retries — These properties guide infrastructure behavior
•Method semantics are contracts — Clients, proxies, and caches rely on these guarantees
•Choose methods based on semantics, not convention — Each method has specific meaning

What's next:

Page Complete