REST API JSON Examples: Requests, Responses and Errors

A REST API with JSON uses HTTP methods on resource URLs (GET /users/42, POST /users) and sends data in both directions as JSON, marked with the header Content-Type: application/json. REST is the architectural style (resources, URLs, HTTP verbs, status codes); JSON is the data format. They're separate things, but almost every RESTful API today speaks JSON, so "REST API" and "JSON API" are often used to mean the same thing.

This page is a reference of REST API JSON examples for a full CRUD cycle, with the status code each step should return, plus the current conventions for errors (RFC 9457), pagination and naming. It also covers JSON:API, the formal spec that shares the name, with an example.

How REST and JSON fit together

• The resource is a noun with a URL: /articles, /articles/1.
• The method says what to do: GET read, POST create, PUT replace, PATCH partially update, DELETE remove (RFC 9110).
• The representation is the resource's data, encoded as JSON (RFC 8259).
• Headers declare formats: Content-Type for what you send, Accept for what you want back.
• The status code tells the client the outcome before it reads the body.

A REST API could return XML or CSV instead; JSON won because it maps directly to objects in JavaScript, Python and most other languages.

REST API JSON examples: a full CRUD cycle

The examples use an articles resource. Run them yourself against JSONPlaceholder, a free fake REST API, by swapping /articles for /posts.

Create: POST returns 201 and a Location header

Request:

POST /articles HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json

{
  "title": "REST and JSON in practice",
  "body": "A short guide.",
  "tags": ["api", "json"]
}

Response:

HTTP/1.1 201 Created
Location: /articles/101
Content-Type: application/json

{
  "id": 101,
  "title": "REST and JSON in practice",
  "body": "A short guide.",
  "tags": ["api", "json"],
  "createdAt": "2026-10-11T09:30:00Z"
}

201 Created plus a Location header pointing to the new resource is what RFC 9110 describes. Return the created object so the client gets server-set fields (id, timestamps) without a second call.

Read one: GET returns 200

GET /articles/101 HTTP/1.1
Accept: application/json

{
  "id": 101,
  "title": "REST and JSON in practice",
  "body": "A short guide.",
  "tags": ["api", "json"],
  "author": { "id": 7, "name": "Ada" },
  "createdAt": "2026-10-11T09:30:00Z",
  "updatedAt": "2026-10-11T09:30:00Z"
}

If the article doesn't exist, return 404 Not Found with an error body (see below), not 200 with null.

Read a list: GET with pagination

GET /articles?limit=2&cursor=eyJpZCI6MTAxfQ HTTP/1.1

{
  "data": [
    { "id": 102, "title": "Pagination patterns" },
    { "id": 103, "title": "Idempotency keys" }
  ],
  "nextCursor": "eyJpZCI6MTAzfQ",
  "hasMore": true
}

Wrap lists in an object rather than returning a bare array: you can add nextCursor, totals or metadata later without breaking clients. Cursor pagination stays correct when rows are inserted while someone pages through; offset pagination (?page=3&limit=20) is simpler but can skip or repeat items.

Update: PATCH for partial changes, PUT for full replacement

PATCH /articles/101 HTTP/1.1
Content-Type: application/merge-patch+json

{ "title": "REST API JSON examples", "tags": null }

{
  "id": 101,
  "title": "REST API JSON examples",
  "body": "A short guide.",
  "updatedAt": "2026-10-11T10:05:00Z"
}

With JSON Merge Patch (RFC 7396), fields you send are changed, null removes a field, and fields you omit stay as they are. Many APIs accept plain application/json with the same semantics. PUT means "replace the whole resource with this body", so a missing field gets cleared.

Delete: 204 No Content

DELETE /articles/101 HTTP/1.1

HTTP/1.1 204 No Content

No body. A second DELETE of the same resource can return 404; the method is still idempotent because the server state is the same either way.

Status codes to use with JSON APIs

Situation	Status
Read succeeded	200 OK
Created a resource	201 Created + Location
Accepted for async processing	202 Accepted
Success, nothing to return	204 No Content
Malformed JSON or bad parameters	400 Bad Request
Not authenticated / not allowed	401 Unauthorized / 403 Forbidden
Resource doesn't exist	404 Not Found
Conflict (duplicate, version mismatch)	409 Conflict
Valid JSON that fails validation	422 Unprocessable Content
Rate limited	429 Too Many Requests + Retry-After
Server bug	500 Internal Server Error

422 is named "Unprocessable Content" in RFC 9110 (older docs say "Unprocessable Entity"). Our 400 Bad Request guide covers when to use 400 versus 422.

JSON error responses: use RFC 9457 problem details

Don't invent a new error shape per endpoint. RFC 9457 (which replaced RFC 7807) defines a standard JSON error format with the media type application/problem+json and five members: type, title, status, detail and instance. You can add your own fields:

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://api.example.com/problems/validation-error",
  "title": "Your request did not validate.",
  "status": 422,
  "detail": "2 fields are invalid.",
  "instance": "/articles",
  "errors": [
    { "pointer": "#/title", "detail": "must not be empty" },
    { "pointer": "#/tags/0", "detail": "must be at most 30 characters" }
  ]
}

Clients can branch on type (a stable identifier) instead of parsing the human-readable detail. Frameworks increasingly support it out of the box, for example ASP.NET Core's ProblemDetails and Spring's ProblemDetail.

JSON naming and format conventions

• Pick one case and keep it. camelCase (common in JavaScript ecosystems) or snake_case (GitHub, Stripe). Mixing them is the real mistake.
• Dates as ISO 8601 / RFC 3339 strings in UTC: "2026-10-11T09:30:00Z", not locale strings or ambiguous timestamps.
• IDs as strings if they might exceed 2^53: JavaScript loses precision on larger integers.
• Money as integer minor units ("amountCents": 1999) or decimal strings, never floats.
• Use null deliberately. Decide whether absent fields are omitted or sent as null, and document it.
• Plural nouns for collections: /articles, /articles/{id}; nest only one level (/articles/{id}/comments).
• Version the API in the path (/v1/) or a header, so you can change the JSON shape later without breaking clients.

What is JSON:API? An example

JSON:API is a specific, formal specification for building JSON APIs, not just "an API that returns JSON". The current version is JSON:API 1.1, with its own media type application/vnd.api+json. Every resource has a type, a string id, attributes and relationships, and related records can be sideloaded in included:

{
  "data": {
    "type": "articles",
    "id": "101",
    "attributes": {
      "title": "REST API JSON examples",
      "createdAt": "2026-10-11T09:30:00Z"
    },
    "relationships": {
      "author": { "data": { "type": "people", "id": "7" } }
    },
    "links": { "self": "https://api.example.com/articles/101" }
  },
  "included": [
    { "type": "people", "id": "7", "attributes": { "name": "Ada" } }
  ]
}

Choose JSON:API if you want conventions for filtering, sparse fieldsets, includes and errors decided for you, plus client libraries that understand them. Most public APIs (Stripe, GitHub) use plain JSON with their own documented conventions instead. Both are valid REST.

Calling a JSON REST API from JavaScript

const res = await fetch("https://jsonplaceholder.typicode.com/posts", {
  method: "POST",
  headers: { "Content-Type": "application/json", Accept: "application/json" },
  body: JSON.stringify({ title: "Hello", body: "From fetch", userId: 1 }),
});

if (!res.ok) {
  const problem = await res.json().catch(() => ({}));
  throw new Error(problem.detail ?? `HTTP ${res.status}`);
}
console.log(res.status, await res.json()); // 201 { ..., id: 101 }

For a step-by-step on making requests in curl, JavaScript and Python, see how to make an API call. To publish your API's JSON shapes, see REST API documentation best practices. Need real JSON APIs to practice against? Browse free APIs for testing.

FAQ

What is the difference between an API and JSON?

An API is an interface that lets programs talk to each other; JSON is a text format for data. A REST API often uses JSON as the format of its requests and responses, but an API can use other formats, and JSON is used in many places besides APIs (config files, logs).

Does a REST API have to use JSON?

No. REST doesn't mandate a format; a REST API can return XML, HTML or anything else. JSON is simply the default for nearly all modern REST APIs.

What Content-Type should a JSON REST API use?

application/json for normal requests and responses, application/problem+json for RFC 9457 error bodies, application/merge-patch+json for JSON Merge Patch, and application/vnd.api+json if you implement the JSON:API spec.

What does a good REST API JSON response look like?

It uses a consistent field naming style, ISO 8601 dates, wraps lists in an object with pagination info, and pairs the correct status code with the body (201 for creates, 404 with a problem-details body for missing resources).

Is JSON:API the same as a JSON REST API?

No. "JSON REST API" is a general description; JSON:API is one specific specification (version 1.1) with strict rules for document structure, relationships and errors.