12. HTTP Requests

RESTful APIs use standard HTTP methods to define operations on resources. API implementations MUST follow the standard semantics of HTTP methods to ensure predictable behavior, interoperability, and correct client/server interaction.

HTTP Method Semantics

GET

GET requests are used to retrieve resources, either individual resources or collections.

Rules:

• GET requests for individual resources should return 404 Not Found if the resource does not exist.

• GET requests for collection resources may return:

  • 200 OK when the collection exists but contains no elements.
  • 404 Not Found when the collection itself does not exist.

• GET requests MUST NOT contain a request body.

Example:

GET /customers/123

Response:

HTTP/1.1 200 OK

{
  "id": "123",
  "name": "John Smith"
}

For collection resources, APIs SHOULD provide filtering and pagination mechanisms.

Example:

GET /customers?status=active&page=1&pageSize=20

PUT

PUT requests are used to replace an entire resource representation.

The semantic is:

Replace the resource identified by the URL with the representation provided in the request payload.

Example:

PUT /customers/123

Request:

{
  "id": "123",
  "name": "John Smith",
  "status": "active"
}

Rules:

• PUT is normally used for individual resources.

• The request payload represents the complete resource.

• Existing resource data is replaced by the new representation.

• Unknown fields SHOULD be ignored rather than stored.

• Successful responses usually return:

  • 200 OK
  • 204 No Content
  • 201 Created when a new resource is created.

Example:

HTTP/1.1 204 No Content

PUT and Resource Creation

Although PUT may create resources, POST SHOULD normally be preferred for creating top-level resources.

When PUT is used for creation:

• The client controls the resource identifier.
• Repeating the same request must be idempotent.

Example:

PUT /customers/customer123

The following two requests should create the same result:

PUT /customers/customer123
PUT /customers/customer123

APIs MAY use ETag with conditional headers such as:

If-Match
If-None-Match

to prevent concurrent update conflicts.

POST

POST requests are primarily used to create new resources under a collection.

The semantic is:

Add the enclosed representation to the collection identified by the URL.

Example:

POST /customers

Request:

{
  "name": "John Smith",
  "status": "active"
}

Response:

HTTP/1.1 201 Created
Location: /customers/123

{
  "id": "123",
  "name": "John Smith",
  "status": "active"
}

Rules:

• The server normally generates the resource identifier.

• The response SHOULD provide the created resource URI.

• Common response codes:

  • 201 Created — resource successfully created.
  • 202 Accepted — request accepted for asynchronous processing.
  • 200 OK — resource updated or operation completed.
  • 204 No Content — successful operation without response body.

Unlike PUT, repeating the same POST request is not guaranteed to produce the same result.

Example:

POST /orders

May create:

Order A
Order B

for two identical requests.

For important scenarios, APIs SHOULD consider making POST operations idempotent.

PATCH

PATCH requests are used to partially update an existing resource.

The semantic is:

Modify the resource identified by the URL according to the changes described in the request.

Example:

PATCH /customers/123

Request:

{
  "status": "inactive"
}

Result:

{
  "id": "123",
  "name": "John Smith",
  "status": "inactive"
}

Rules:

• PATCH normally applies to individual resources.

• PATCH usually requires the resource to already exist.

• Only specified fields are updated.

• Successful responses usually return:

  • 200 OK
  • 204 No Content

Recommended PATCH Patterns

To avoid inconsistent implementations, APIs SHOULD select one update pattern per endpoint.

Recommended order:

1. Prefer PUT when possible

Use full resource replacement:

PUT /customers/123

with the complete object.

2. JSON Merge Patch

Use partial objects:

Content-Type:

application/merge-patch+json

Example:

{
  "status": "inactive"
}

3. JSON Patch

Use operation-based updates:

Content-Type:

application/json-patch+json

Example:

[
  {
    "op": "replace",
    "path": "/status",
    "value": "inactive"
  }
]

4. Use POST for special operations

If the update behavior cannot be represented by PATCH semantics, use POST and document the behavior clearly.

DELETE

DELETE requests remove resources.

The semantic is:

Delete the resource identified by the URL.

Example:

DELETE /customers/123

Successful responses:

HTTP/1.1 204 No Content

or:

HTTP/1.1 200 OK

with deleted resource information.

Rules:

• DELETE normally applies to individual resources.
• Deleting a collection resource is discouraged because it implies deleting the entire collection.
• After deletion, subsequent GET requests should return:

404 Not Found

or:

410 Gone

The deleted resource MUST NOT remain accessible.

HEAD

HEAD has the same semantics as GET, but returns only HTTP headers.

Example:

HEAD /customers/123

Response:

HTTP/1.1 200 OK
Content-Length: 1024
ETag: "abc123"

Typical usage:

• Check whether a resource exists.
• Check metadata.
• Validate cache information.

OPTIONS

OPTIONS is used to discover supported operations for an endpoint.

Example:

OPTIONS /customers/123

Response:

Allow: GET, PUT, DELETE

It may also describe available operations or supported capabilities.

HTTP Method Properties

HTTP methods have three important characteristics:

Safe

A safe operation does not intentionally modify server state.

Examples:

Safe:

• GET
• HEAD
• OPTIONS

Not safe:

• POST
• PUT
• PATCH
• DELETE

Idempotent

An idempotent operation produces the same intended server state when executed multiple times.

Examples:

Example:

PUT /customers/123

Executing:

PUT /customers/123
PUT /customers/123

results in the same resource state.

Cacheable

Responses may be stored and reused.

Typical cacheable methods:

• GET
• HEAD

Some POST responses may be cacheable if explicitly defined.

Query Parameters

Query parameters SHOULD be used for resource filtering and simple queries.

Example:

GET /customers?name=John

Filtering definitions SHOULD specify:

• Related resource property.
• Allowed value range.
• Comparison behavior.
• Combination rules.

Examples:

Equality:

name=John

Range:

ageGreaterThan=18

Time filtering:

createdBefore=2026-01-01

Complex Operations

Complex operations SHOULD be modeled as resources instead of adding verbs into URLs.

Avoid:

POST /customers/searchCustomers

Prefer:

POST /customers/searches

Request:

{
  "query": "complex search criteria"
}

Response:

HTTP/1.1 201 Created

{
  "id": "search123",
  "results": {
    "items": []
  }
}

For asynchronous processing:

HTTP/1.1 202 Accepted
Location: /customers/searches/search123

Client can later query:

GET /customers/searches/search123

Asynchronous Request Tracking

When an API returns:

202 Accepted

the response SHOULD provide a way to track execution status.

Example:

Request:

POST /customers

Response:

HTTP/1.1 202 Accepted

{
  "id": "123",
  "meta": {
    "status": "pending"
  }
}

Recommended status values:

queued
pending
processing
cancelled
failed
completed

The client can poll:

GET /customers/123

until completion.

Alternative:

Return a dedicated job resource:

{
  "job": {
    "id": "456",
    "href": "/jobs/456",
    "status": "processing"
  }
}

Then query:

GET /jobs/456

Response:

{
  "id": "456",
  "status": "completed",
  "customer": {
    "href": "/customers/123"
  }
}

Summary

REST API design should rely on standard HTTP semantics rather than creating custom action-style endpoints. This improves predictability, interoperability, caching behavior, and long-term API evolution.