Backend
Beginner 12 min read Backend

HTTP & REST APIs

HTTP is the request/response protocol that powers the web. REST is an architectural style that uses HTTP verbs, resource URLs and status codes to design APIs that are predictable and easy to consume.

HTTPRESTresourcesstatus codescurlCRUD
Introduction

What is this?

HTTP is a stateless request/response protocol where a client sends a request (method, URL, headers, body) and a server answers with a status code, headers and a response body. REST is an architectural style layered on top of HTTP: data is modeled as resources, addressed by URLs, and manipulated with the standard verbs GET, POST, PUT, PATCH and DELETE.

Motivation

Why do you need it?

  • Stateless requests make services horizontally scalable — any instance can serve any request.
  • Reusing HTTP verbs and status codes gives every client a shared, predictable contract.
  • Resources are addressable by URL, so clients can cache, bookmark and link to specific data.
  • Because it runs over HTTP(S), REST APIs work with any language, tool or proxy without special software.
Think about it

Mental model

Imagine

A well-run restaurant kitchen

Think of

A REST API

The menu is the API contract, the order ticket is the request, the served dish is the response, and the ticket number lets you check on an order (status) the same way a status code tells you what happened.

Mechanics

How it works

  • The client sends an HTTP request line like GET /users/42 with headers (Accept, Authorization) and an optional body.
  • The server matches the method and URL to a route handler using its routing table.
  • The handler executes business logic, reads or writes data, and builds a response with a status code (200 OK, 404 Not Found, etc.).
  • The response travels back with headers (Content-Type, Cache-Control) and a body, usually JSON.
  • The client reads the status code and body; because each request is independent, the server keeps no memory between requests.

A single REST round-trip: client request, server processing, response.

Client
HTTP request
Router
Handler + data store
HTTP response
Client renders result
Reference

Key commands

curl -i https://api.example.com/users

Send a GET request and print the response headers (-i) alongside the body.

HTTP/2 200\nContent-Type: application/json\n[{"id":42,"name":"Ada"}]
curl -X POST -H 'Content-Type: application/json' -d '{"name":"Ada"}' https://api.example.com/users

Create a resource by sending a JSON body with the POST verb.

HTTP/2 201\n{"id":43,"name":"Ada"}
curl -o /dev/null -w '%{http_code}' https://api.example.com/users/42

Print only the HTTP status code, useful in scripts and health checks.

200
curl -s https://api.example.com/users/42 | jq .name

Pipe the JSON response through jq to extract a single field.

"Ada"
curl -sI https://api.example.com/users/42

Send a HEAD request to read headers only, without downloading the body.

HTTP/2 200\ncontent-type: application/json\netag: "ab12cd"
Hands-on

Examples

Interacting with a REST API using curl

Interacting with a REST API using curl
# Read: fetch one user
curl -i https://api.example.com/users/42
 
# Create: POST a new user
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Ada", "email": "ada@example.com"}'
 
# Update: PATCH a partial change
curl -X PATCH https://api.example.com/users/42 \
  -H "Content-Type: application/json" \
  -d '{"email": "ada.lovelace@example.com"}'
 
# Delete
curl -X DELETE https://api.example.com/users/42

Each curl call exercises one REST verb against a resource. -i prints the response headers so you can see the status code and Content-Type. GET is read-only, POST creates, PATCH updates part of a resource, and DELETE removes it — the same URL means the same resource in every call.

Real world

In production

  • Mobile and web clients consume REST endpoints for CRUD on users, orders and content.
  • BFFs (backend-for-frontend) aggregate several REST calls into one response tailored to a UI.
  • Public developer platforms (Stripe, GitHub, Twilio) expose REST APIs documented with OpenAPI.
  • Third-party services integrate through REST using API keys in the Authorization header.
Guidelines

Best practices

  • Name resources as nouns in the plural (GET /users, not GET /getUsers) and keep URLs flat.
  • Use the correct verb: GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes.
  • Return meaningful status codes (200, 201, 400, 401, 403, 404, 429, 500) with consistent JSON error bodies.
  • Version the API (v1) and use HTTP caching headers for read endpoints.
  • Document the contract with OpenAPI so clients and tools can generate clients and tests.
Watch out

Common mistakes

  • Putting actions in URLs (GET /users/delete/42) instead of using the DELETE verb.
  • Returning 200 for every outcome, forcing clients to inspect the body to detect errors.
  • Using HTTP verbs as verbs in resource names (GET /createUser) — verbs belong to the protocol.
  • Leaking stack traces or database details in error responses.
Root cause analysis

Common issues

Error
404 Not Found
Root cause

The URL or method does not match any registered route.

Fix

Verify the path spelling and that the verb matches the route (GET vs POST).

Error
405 Method Not Allowed
Root cause

The route exists but the verb used is not supported on it.

Fix

Check the route definition and use the verb it registers (POST instead of GET).

Error
400 Bad Request / 422 Unprocessable Entity
Root cause

The request body is malformed or fails validation.

Fix

Validate the JSON and required fields; fix the payload before resending.

When things break

Debugging tips

  • curl -i and -v show every header, which is where redirects, cookies and caching live.
  • Check the status code before the body: 4xx is a client problem, 5xx is a server problem.
  • Use a REST client (Postman, Insomnia, HTTPie) to replay and edit requests quickly.
  • Add request IDs and timestamps so you can correlate a failing call with server logs.
Interviews

Interview checkpoint

Practice

Hands-on lab

Talk to a REST API with curl
25 min · beginner
In progress
Objectives
  • Understand the anatomy of an HTTP request and response
  • Practice the CRUD verbs GET, POST, PATCH and DELETE
  • Read status codes and headers
  • Pipe JSON responses through jq

Talk to a REST API with curl

25 min · beginner

0/5 steps
0%
sandbox · Linux sandbox
$
Try these commands
Test yourself

Quick quiz

0/3
1

Which HTTP verb should be used to fully replace an existing resource?

2

Which status code means the request was valid but the server is refusing it due to insufficient permissions?

3

REST APIs must be stateless, meaning each request must contain all the information needed to process it.

Quick reference

Cheat sheet

HTTP verbs
GETRead a resource, no side effects
POSTCreate a resource
PUTReplace a resource entirely
PATCHApply a partial update
DELETERemove a resource
Common status codes
200 / 201OK / Created
400 / 401 / 403Bad request / Unauthenticated / Forbidden
404 / 409Not found / Conflict
429 / 500 / 503Rate limited / Server error / Unavailable
Go deeper

Official documentation

MDN — An overview of HTTP
docs
MDN — HTTP request methods
docs
MDN — HTTP response status codes
docs
IETF RFC 9110 — HTTP Semantics
rfc