REST API JSON Basics: Methods, Status Codes, and Payloads

REST and JSON usually travel together

REST-style APIs organize behavior around resources and HTTP methods. JSON is the most common representation those APIs read and write. Understanding the pairing—method + status + JSON body—makes integrations predictable.

Methods and typical JSON roles

Method	Typical use	Body
GET	Read	Usually none; JSON in response
POST	Create / actions	JSON request + response
PUT	Replace	JSON request + response
PATCH	Partial update	JSON request + response
DELETE	Remove	Often empty; sometimes JSON receipt

Example create:

POST /api/tasks HTTP/1.1
Content-Type: application/json

{"title":"Write docs","done":false}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{"id":"tsk_22","title":"Write docs","done":false}

Status codes that match JSON outcomes

• 200 — OK with a JSON body
• 201 — Created; return the new resource
• 204 — Success with no body (common for DELETE)
• 400 / 422 — Client validation problems; return error JSON
• 401 / 403 — Auth/authz failures; minimal safe JSON
• 404 — Missing resource
• 409 — Conflict (duplicate key, version mismatch)
• 500 — Server failure; never dump stack traces to public clients

Clients should branch on status first, then parse JSON. A 200 with { "success": false } is a design smell—use proper codes.

Idempotency and JSON

PUT and DELETE are typically idempotent. POST often is not. If clients retry POSTs, support idempotency keys in headers and document how duplicate JSON submissions behave. Returning the same created resource for a repeated key prevents double charges and duplicate rows.

Partial updates with PATCH

{ "done": true }

means “change only done,” not “wipe every other field.” If you implement PUT as full replace, document required fields clearly so clients do not accidentally null out data.

Query parameters vs. JSON bodies

GET requests should not rely on JSON bodies—many intermediaries ignore them. Use query strings for filters: /tasks?done=false&limit=20. Reserve JSON bodies for writes and complex search POSTs when your API explicitly supports them.

Debugging REST JSON quickly

Reproduce with curl or an HTTP client, copy the body, and validate it. Pretty-print responses to inspect nesting. JSON Editor helps you format and validate samples while you reconcile docs with reality.

Security basics

• HTTPS everywhere
• Do not put secrets in JSON that ends up in logs by default
• Validate size limits to avoid huge payload DoS
• Sanitize error messages

Mental model to keep

REST organizes where and how you call; JSON shapes what you send. Master both: the cleanest payload cannot save a wrong method, and a perfect status code cannot fix ambiguous field names. Align method, code, and body—and your API will feel boring in the best way.