REST API Tutorial: HTTP Methods, Status Codes, Headers, and curl

REST uses HTTP verbs to mean operations on resources; clients and servers must agree on status codes so automation (and humans) know whether to retry, re-auth, or fix input. curl is shown because it is everywhere—each flag exists to surface headers, errors, or request bodies for debugging.

Pair this guide with environment variables for tokens and Node.js when you implement servers.

HTTP methods

Why verbs matter: Intermediaries (caches, proxies) treat GET as safe to repeat; POST may create side effects—using the wrong verb breaks caching and idempotency expectations.

• GET — read a resource; should not change server state.
• POST — create an action or sub-resource; body often JSON.
• PUT — replace a resource (idempotent when URL identifies the resource).
• PATCH — partial update.
• DELETE — remove (often idempotent).

Status codes (cheat sheet)

Code	Meaning	Why clients care
200	OK — success with body	Parse response as the happy path
201	Created — new resource	Use Location header if present
204	No content — success, empty body	Stop parsing JSON—there is none
400	Bad request — client error	Fix payload or query before retry
401	Unauthorized — authenticate	Refresh token or log in
403	Forbidden — authenticated but not allowed	Do not retry blindly—policy issue
404	Not found	Check URL or resource lifecycle
409	Conflict	Merge or resolve state (duplicate, version)
429	Too many requests	Honor Retry-After backoff
500	Server error	Retry with jitter; alert ops if persistent

Headers and JSON

Why Content-Type: Servers pick parsers based on this header; wrong types yield 415 or silent mis-parsing.

Set Content-Type: application/json on requests with a JSON body. For auth, Authorization: Bearer <token> is common for APIs—keep tokens out of Git and load from env vars.

Test with curl

Why -sS: Hide progress meter for scripts but still show errors; add -i when you need response headers to debug auth or caching.

curl -sS https://api.example.com/v1/items
curl -sS -X POST https://api.example.com/v1/items \
  -H "Content-Type: application/json" \
  -d '{"name":"demo"}'

Add -H "Authorization: Bearer $TOKEN" when required.

Check: HTTP status on first line (with -i); JSON body should match API docs.

OpenAPI

Why OpenAPI: A machine-readable contract lets you generate clients, mock servers, and contract tests—humans stop being the single source of truth for URLs and schemas.

Frequently asked questions

Is REST the same as HTTP?

REST is an architectural style using HTTP; not every JSON HTTP API is strictly RESTful, but the same tools apply.

What is idempotency?

Repeating the same safe request does not compound side effects—important for retries on PUT/DELETE.

How do APIs paginate?

Common patterns: ?page= and limit, or cursor tokens in the response for stable large datasets.

GraphQL instead?

GraphQL uses a single endpoint and client-specified fields; choose based on product and client needs, not hype.