REST API Request and Response Patterns

JSON request bodies, envelope choices, sparse fieldsets, includes, concurrency control, and common response contracts.

View

Export

Copy the compact sheet, download it, or print it.

Download

`D` dense toggle · `C` copy all

## JSON request patterns

Simple create request body

{
  "name": "Ava Martin",
  "email": "ava@example.com",
  "role": "admin"
}

# POST a resource representation.

Partial update body

{
  "timezone": "America/Los_Angeles",
  "marketing_opt_in": false
}

# PATCH with only the fields that change.

Bulk create request

{
  "items": [
    { "sku": "sku_1", "qty": 2 },
    { "sku": "sku_2", "qty": 1 }
  ]
}

# Submit multiple items in one call when needed.

## Response shaping

Sparse fieldsets

GET /users/usr_123?fields=id,name,email

# Return only requested fields.

Return an ETag for concurrency and caching

ETag: "686897696a7c876b7e"

# Tag a representation with a revision validator.

Protect updates with If-Match

PATCH /documents/doc_123
If-Match: "686897696a7c876b7e"

# Prevent lost updates from concurrent writes.

Represent async work as a job resource

{
  "id": "job_123",
  "status": "queued",
  "url": "/jobs/job_123"
}

# Queue work and let clients poll job state.

More in REST API

No recommendations yet.