An API Call Is an HTTP Request

A call to a web API is an HTTP request: a method saying what to do, a path naming what to do it to, headers carrying details, and sometimes a body with data. The server answers with a status code saying how it went, its own headers, and usually a body. Of all these parts, the method is the one every piece of software between client and server reads to decide what it may do with the call.

Here is one call that adds an item to order 42, and the reply. The exchange is illustrative.

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

{"sku":"pen-blue","quantity":3}

HTTP/1.1 201 Created
Location: /orders/42/items/7
Content-Type: application/json

{"id":7,"sku":"pen-blue","quantity":3}

The method, POST, says what the client intends. HTTP defines a small set, and each comes with promises about whether it changes anything and whether it can be repeated.

The path, /orders/42/items, names the resource: the thing on the server the request is about. Here it is the list of items in one order.

The headers are lines of name: value. Content-Type says the body is JSON, and Authorization carries the caller's credentials. A header is information about the message rather than the message itself.

The body carries the data, here the item to add. Many requests, such as reads, have none.

The status code, 201, is a three-digit number saying what happened. 201 Created means a new resource exists, and the Location header says where.

Between the client and the API there are often other programs: a CDN, a network of servers that stores copies of responses near users; a proxy or gateway that forwards requests; the client's own retry library. None of them understands what /orders/42/items means. All of them understand POST, and they decide from it whether a response may be stored and reused, or a failed request sent again.

So choosing the method is not a style decision. It is the one part of the call that tells everything in between what the call may safely do.