~/learn / apis

How APIs Work

What an API is, exactly what travels over the wire in a request and response, how methods, status codes, idempotency, and content negotiation behave, and how to read and make calls yourself.

beginnerupdated

An API (application programming interface) is a contract that lets one program ask another to do something. When a weather app shows today’s forecast, it did not compute it. It sent a request to a weather service’s API and displayed the answer. The contract is the point: each side can change internally as long as the request and response shapes hold.

Modern websites are mostly APIs with a user interface painted on top. The page in your browser is a client; the real work happens in API calls you can watch under the Network tab of developer tools. That is why API fluency matters so much for security: the API, not the rendered page, is the actual attack surface, and it often exposes more than the UI ever shows.

A request, piece by piece

Most web APIs speak HTTP. A complete request:

POST /v1/orders HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
Accept: application/json

{"productId": "sku-881", "quantity": 2}
Part Example Purpose
Method POST What kind of action
Path /v1/orders Which resource
Headers Authorization, Content-Type Metadata: who you are, what the body is
Body the JSON The data you are sending

And the response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /v1/orders/5521

{"id": 5521, "status": "pending", "total": 39.98}

The blank line separates headers from body in both directions, which is the same framing that makes header-injection and request-smuggling bugs possible when a proxy and a server disagree about where that line falls. On HTTP/1.1 this is literally text on the wire; HTTP/2 and HTTP/3 carry the same semantics as binary frames over a multiplexed connection, which is faster but preserves the method, path, headers, and body you reason about here.

Methods

Method Meaning Safe to repeat?
GET Read something Yes, it must change nothing
POST Create, or perform an action No
PUT Replace entirely Yes, same result each time
PATCH Change part Depends
DELETE Remove Yes, it is already gone

“Safe to repeat” is idempotency, and getting it wrong produces real bugs: a double-charged card from a retried POST, or a GET that changes state and so can be triggered by a prefetch, an image tag, or a link (which is also how it becomes a CSRF target). Serious write APIs accept an idempotency key, a client-supplied unique id the server records so a retried request returns the original result instead of acting twice. That one header is how payment APIs make network retries safe.

Status codes

Range Meaning Codes worth knowing
2xx Success 200 OK, 201 Created, 204 No Content
3xx Look elsewhere 301, 302, 304 Not Modified
4xx Your request was wrong 400 bad input, 401 unauthenticated, 403 forbidden, 404 not found, 422 unprocessable, 429 too many requests
5xx The server failed 500 crash, 502/503 upstream or overload

The difference between 401 and 403 matters in testing: 401 means “I do not know who you are,” 403 means “I know who you are, and no.” A 404 where you expected 403 can be deliberate (hiding whether a record exists) or a bug (the check ran on the wrong thing).

Content negotiation

Headers let client and server agree on format without changing the URL. Accept: application/json asks for JSON; Content-Type declares what you are sending; Accept-Encoding negotiates gzip or brotli; Accept-Language picks a locale. This flexibility is also an attack surface: an endpoint that accepts both JSON and XML may route XML to a parser with external entities enabled (XXE), and a server that trusts Content-Type to pick a body parser can be steered into the weaker one.

Make your first call

curl is the universal API client. Try a public practice API:

curl -s https://jsonplaceholder.typicode.com/posts/1
curl -s -X POST https://jsonplaceholder.typicode.com/posts \
  -H 'Content-Type: application/json' \
  -d '{"title": "hello", "body": "from curl", "userId": 1}'
curl -si https://jsonplaceholder.typicode.com/posts/1 | head -20   # -i shows headers

Pipe JSON through jq to read it: curl -s ... | jq .. Watching the raw headers with -i is the habit that makes API testing click, because the body is only half the story.

API styles

  • REST organizes everything around resources and URLs, using HTTP methods as verbs. Most public APIs.
  • GraphQL exposes one endpoint where the client asks for exactly the fields it wants.
  • SOAP wraps every call in an XML envelope described by a machine-readable WSDL contract. Older, verbose, and still everywhere in enterprise, banking, and government systems.
  • gRPC uses binary Protocol Buffers over HTTP/2, common between internal services.
  • Webhooks reverse the direction: the API calls you when something happens, which means you are now the server validating an inbound request.

The next pages cover REST and GraphQL in detail, the XML world of SOAP, how APIs authenticate callers, and how to test APIs for security issues.

Go deeper