Anatomy of an HTTP Message

Designing an API well starts with seeing exactly what goes over the wire. An HTTP exchange is just text: a request from the client and a response from the server, each with the same three parts.

The request

A request has a start line (method + target + HTTP version), a set of headers, and an optional body:

POST /articles HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGci...
Accept: application/json

{ "title": "Designing APIs", "body": "..." }

The method (POST) says what to do; the target (/articles) says to what; the headers carry metadata (content type, auth, what the client accepts); the body carries the payload.

The response

The response mirrors that shape: a status line (version + status code + reason), headers, and an optional body:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /articles/42

{ "id": 42, "title": "Designing APIs" }

flowchart LR
  subgraph Request
    A[Start line: method + path] --> B[Headers] --> C[Body optional]
  end
  subgraph Response
    D[Status line: code + reason] --> E[Headers] --> F[Body optional]
  end
  Request -->|over HTTP| Response

Request and response share the same three-part structure

Building a response in code

Server frameworks hide most of this, but it helps to construct a response by hand once. This snippet builds the headers and JSON body for a “created” response and logs them:

JavaScript

function buildCreated(resource) {
  const body = JSON.stringify(resource);
  const headers = {
    'Content-Type': 'application/json',
    'Content-Length': String(body.length),
    'Location': '/articles/' + resource.id,
  };
  return { status: 201, headers, body };
}

const res = buildCreated({ id: 42, title: 'Designing APIs' });
console.log('status:', res.status);
console.log('headers:', res.headers);
console.log('body:', res.body);