Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 30 ยท Getting Started

HTTP and REST in ten minutes

Learn the HTTP basics every API tester needs: requests, methods, status codes, headers, bodies, idempotency and REST resources, with runnable examples.

Postman, Newman and almost every other API testing tool are really just clever ways of sending HTTP messages and reading the replies. If you understand what an HTTP request and response contain, every screen in Postman will make sense. This lesson is a fast, practical tour of the protocol, followed by the conventions called REST that most web APIs follow.

The real internet is not available inside the examples on this page. Instead, the runnable code starts a small HTTP server on the same machine (a stand-in for a real API) and calls it with fetch, so you can see real requests and responses. The server and the client are real HTTP; only the "API" itself is a toy.

Requests and responses

HTTP is a conversation in which the client always speaks first. The client sends a request, and the server sends back exactly one response.

A request has four parts

Method What you want to do, such as GET.
URL Which resource, plus optional query.
Headers Extra facts about the request.
Body Optional data, such as JSON.
1 / 2

On the wire, a request is plain text. This one asks for a list of notes:

HTTP
GET /notes?limit=2 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer abc123

The first line is the request line: method, path with query string, and protocol version. The lines after it are headers, each Name: value. A blank line ends the headers, and anything after it is the body. A matching response looks like this:

HTTP
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

[{"id":1,"text":"buy milk"},{"id":2,"text":"call Sam"}]

The first line is the status line: version, status code and a short reason phrase. Then come the response headers, a blank line, and the body.

Methods

The method tells the server what you intend to do. The common ones map neatly onto working with data:

Method Typical use Safe? Idempotent?
GET Read a resource or a list Yes Yes
POST Create something, or trigger an action No No
PUT Replace a resource completely No Yes
PATCH Change part of a resource No Not guaranteed
DELETE Remove a resource No Yes

Safe means the request is not supposed to change anything on the server. Idempotent means that sending the same request several times leaves the server in the same state as sending it once. This matters to testers: if a network glitch makes a client retry, an idempotent request is harmless, while repeating a POST may create a duplicate.

Status codes

The status code is a three-digit number, and its first digit tells you the category.

Status code families

2xx Success 200 OK, 201 Created, 204 No Content.
3xx Redirect 301 and 302 point elsewhere, 304 Not Modified.
4xx Client error 400 Bad Request, 401, 403, 404, 422.
5xx Server error 500 and 503 mean the server failed.

4xx means the request was wrong. 5xx means the server was wrong.

1 / 2

A few codes appear in nearly every test suite:

  • 200 OK: the request worked and the body holds the result.
  • 201 Created: a new resource was created; the Location header often gives its address.
  • 204 No Content: success, with intentionally no body (common after DELETE).
  • 400 Bad Request: the server could not understand or accept the request as sent.
  • 401 Unauthorized: you are not authenticated (missing or bad credentials).
  • 403 Forbidden: you are authenticated but not allowed to do this.
  • 404 Not Found: no such resource.
  • 422 Unprocessable Content: the request was well-formed but failed validation. Some APIs use 400 for this instead, so always check the documentation.
  • 500 Internal Server Error: something broke on the server.

Headers and bodies

Headers are name/value pairs that describe the message. A few you will meet constantly:

  • Content-Type: the format of the body being sent (application/json).
  • Accept: the formats the client is willing to receive.
  • Authorization: credentials, covered in Authentication: API keys, Basic, Bearer and OAuth 2.0.
  • Location: where a newly created resource lives, or where a redirect leads.
  • Cache-Control: whether and how long a response may be stored.

Header names are case-insensitive, so Content-Type and content-type are the same header. The body carries data. JSON is by far the most common format for APIs, but bodies can also be form data, XML, plain text or raw bytes. GET requests normally have no body.

Run the example below. It starts a local server, sends a POST with a JSON body, and prints what each side saw.

Node.js One request and one response, end to end

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.

Read the output in two halves. The lines starting with SERVER show the request exactly as it arrived: the method, the path including the ?draft=true query string, the Content-Type header and the raw body text. The lines starting with CLIENT show the response: status 201, the headers the server chose, and the parsed JSON body. This is precisely the information Postman displays in its request and response panels.

REST: resources and URLs

REST is a style for designing HTTP APIs around resources: things such as users, orders or notes. The conventions are simple:

  • Use nouns in URLs, usually plural: /notes, not /getNotes.
  • A collection lives at /notes; a single item at /notes/7.
  • The method supplies the verb: GET /notes/7 reads, DELETE /notes/7 removes.
  • Send and receive representations (usually JSON) of the resource.
  • Each request stands alone: the server does not rely on remembering your earlier requests, so credentials travel with every call.
Request Meaning
GET /notes List notes
POST /notes Create a note
GET /notes/7 Read note 7
PUT /notes/7 Replace note 7
PATCH /notes/7 Change part of note 7
DELETE /notes/7 Delete note 7

Many real APIs bend these rules a little, so treat REST as a convention to check against, not a law.

Seeing idempotency in action

The next stand-in is a tiny notes API. We send the same request twice and count what happens to the data. This is exactly the kind of experiment you would run to learn how a real API behaves.

Node.js POST, PUT and DELETE sent twice

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 two POST requests produce two notes, so the count rises each time (1, then 2). The first PUT stores note 10 (the count becomes 3), and the identical second PUT changes nothing: the count stays at 3. The two DELETE requests leave the server in the same state (note 10 is gone, the count is back to 2), although the response differs: 204 the first time, 404 the second. Idempotent describes the server's state, not that the response is identical.

Real APIs come with their own rules, and some break the conventions above. Always read the API's documentation and test what it actually does. This stand-in server follows common conventions, but it is only a model of a real one.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which part of an HTTP request tells the server what you want to do?

    The method (GET, POST, PUT, PATCH, DELETE...) states the intended action. Status codes and reason phrases belong to responses.
  2. 2. A client sends a valid login token but tries to open a page it is not allowed to see. Which status fits best?

    403 means the server knows who you are but refuses the action. 401 is for missing or invalid credentials.
  3. 3. Why is sending the same POST twice risky compared with sending the same PUT twice?

    POST is not idempotent: repeating it can create duplicates. A PUT to the same URL with the same body leaves the same state.
  4. 4. Which URL follows common REST naming conventions for reading order 15?

    REST uses plural nouns in the path and lets the method be the verb. GET /orders/15 reads order 15.

Summary

  • A request has a method, a URL, headers and an optional body; a response has a status code, headers and a body.
  • Status codes group by first digit: 2xx success, 3xx redirect, 4xx client error, 5xx server error.
  • Headers describe messages; Content-Type, Accept, Authorization and Location appear constantly.
  • Safe methods do not change data; idempotent methods leave the same server state when repeated.
  • REST organizes APIs around resources with plural-noun URLs, and the method is the verb.
  • Real APIs may deviate from the conventions, so test what they do.
  • The examples here used a local stand-in server, not a real internet API.

Next: Installing Postman and a tour of the interface.