Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 39 ยท HTTP and REST Fundamentals

HTTP Requests and Responses

See what an HTTP message really looks like: request line, headers, body, status line, URL parts and how fetch maps to the raw text on the wire.

Every REST API call is an HTTP exchange: one request message goes from the client to the server, and one response message comes back. Libraries such as fetch hide the details, but when something breaks (a missing header, a wrong content type, a body that never parses) you debug the messages themselves. This lesson shows exactly what they look like.

HTTP/1.1 messages are plain text. HTTP/2 and HTTP/3 carry the same information in a binary framing, but the concepts (method, target, status, headers, body) are identical, so learning the text form is enough.

Anatomy of a request

HTTP
POST /books?lang=en HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer abc123
Content-Length: 31

{"title":"Dune","year":1965}

A request has four parts:

  1. Request line: method (POST), request target (/books?lang=en) and protocol version.
  2. Headers: Name: value lines. Host is mandatory in HTTP/1.1 because one IP address can serve many sites.
  3. A blank line that ends the headers.
  4. Body (optional): the data. GET and DELETE normally have none.

Anatomy of a response

HTTP
HTTP/1.1 201 Created
Content-Type: application/json
Location: /books/43
Content-Length: 44

{"id":43,"title":"Dune","year":1965}
  1. Status line: version, a three-digit status code and a reason phrase. The code is what programs read; the phrase is for humans. See status codes.
  2. Headers: metadata about the response.
  3. Blank line, then the body.

Taking a URL apart

The request target in the first line is only part of the address. The full URL has several pieces, and each plays a role in API design:

flowchart LR
    A["https://"] --> B["api.example.com"] --> C[":443"] --> D["/v1/books/42"] --> E["?fields=title"] --> F["#top"]

scheme, host, port, path, query and fragment.

  • Scheme (https) chooses the protocol. Always use HTTPS for APIs.
  • Host and port pick the server. The port defaults to 443 for HTTPS and 80 for HTTP.
  • Path (/v1/books/42) identifies the resource.
  • Query (?fields=title) carries optional parameters such as filters. See filtering and sorting.
  • Fragment (#top) never reaches the server; it is for the client only.

JavaScript's URL class parses all of this, and the next example uses it.

Look at real bytes

Node's node:net module lets you open a raw TCP socket, so you can type an HTTP request by hand and read the response exactly as the server wrote it. The server below is an ordinary node:http server; the client is a plain socket.

Node.js A hand-written HTTP request

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The response begins with HTTP/1.1 200 OK, then headers (Node adds Connection and others on its own), an empty line and finally the JSON body. Every REST client you will ever use produces and consumes exactly this.

From fetch to messages

fetch builds the request message for you from a URL and an options object, and gives you back a Response object with the parsed pieces:

Node.js What fetch sends and receives

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

A few things to notice:

  • response.ok is true for any status from 200 to 299.
  • fetch does not throw on 404 or 500. It only rejects on network failures. Always check response.ok or response.status.
  • The body can be read once: response.json(), response.text() and friends consume the stream.
  • Header names are case-insensitive. Content-Type, content-type and CONTENT-TYPE are the same header.

Body formats and Content-Length

The body is just bytes. Two headers explain how to read them:

  • Content-Type says what the bytes mean (application/json, text/csv, multipart/form-data).
  • Content-Length says how many bytes there are. If the server does not know in advance (for example while streaming), it uses Transfer-Encoding: chunked instead.

A common bug is sending JSON with fetch but forgetting Content-Type: application/json. The server then sees text/plain and may refuse to parse it. When a body "arrives empty" on the server, check this header first.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which part of an HTTP request separates the headers from the body?

    Headers end with an empty line (CRLF CRLF). Everything after it is the body.
  2. 2. What happens when fetch receives a 404 response?

    fetch only rejects on network-level failures. HTTP error statuses resolve normally, so you must check response.ok.
  3. 3. Which part of the URL https://api.example.com/books?limit=5#top never reaches the server?

    The fragment is handled by the client only and is not sent in the request.
  4. 4. Why does a POST with a JSON string sometimes arrive at the server as unparsed text?

    Servers choose a parser from Content-Type. Without application/json the body may be treated as plain text.

Summary

  • A request is a request line, headers, a blank line and an optional body; a response is a status line, headers, a blank line and a body.
  • The URL has scheme, host, port, path, query and fragment; each has a role in API design.
  • fetch does not reject on error statuses; check response.ok.
  • Content-Type and Content-Length tell the receiver how to read the bytes.
  • Header names are case-insensitive, and bodies can be read only once.

Next: HTTP Methods and Idempotency