APIs from zero
Requests — addresses and methods
Every API request says where to go (the URL) and what to do (the method). How URLs are built, and what GET, POST, PUT, PATCH and DELETE mean.
Every request answers two questions: where? and what should happen there? The where is the URL. The what is the method.
The URL: an address, piece by piece
https://api.shop.example.com:443/v2/orders/A-1001?expand=items&lang=en
└─┬─┘ └─────────┬─────────┘└┬┘└──────┬───────┘└─────────┬─────────┘
scheme host port path query
- Scheme —
https(encrypted) orhttp(not encrypted). Real APIs should usehttps;httpis fine on your own computer. - Host — which server:
api.shop.example.com. On your own computer it'slocalhostor127.0.0.1. - Port — which "door" on that server. Usually left out:
httpsmeans 443 andhttpmeans 80. Programs you run yourself often use others, likelocalhost:3000orlocalhost:8080. - Path — which thing on the server:
/v2/orders/A-1001. It often reads like folders: version 2 → orders → order A-1001. - Query — extra details after a
?, asname=valuepairs joined by&:expand=items&lang=en. Used for options like filters, sorting and pages.
The part from the scheme to the port — https://api.shop.example.com — is the base URL. One API usually has one base URL and many paths. That's why tools let you store the base URL once (in APITestCenter as {{baseUrl}}) and write each request as just its path: {{baseUrl}}/orders.
Resources: the nouns of an API
Most web APIs are organised around resources — the things the API is about: products, orders, users, invoices. A good path names a resource:
| Path | Means |
|---|---|
/orders | all orders (a collection) |
/orders/A-1001 | one order |
/orders/A-1001/items | the items of that order |
/users/42/orders | the orders of user 42 |
The method then says what to do with it.
The method: what to do
| Method | Means | Example | Has a body? |
|---|---|---|---|
| GET | Read — give me this | GET /orders/A-1001 | No |
| POST | Create — make a new one (or do something) | POST /orders with the new order | Yes |
| PUT | Replace — make this one exactly like this | PUT /users/42 with the whole user | Yes |
| PATCH | Change part of it | PATCH /users/42 with just { "email": "…" } | Yes |
| DELETE | Remove it | DELETE /orders/A-1001 | Usually no |
| HEAD | Like GET, but only the headers — does it exist, how big is it? | No | |
| OPTIONS | What may I do here? (browsers ask this before some requests) | No |
The same path with different methods does different things: GET /orders lists orders, POST /orders creates one.
Safe and idempotent: two words worth knowing
- A safe method only reads; it changes nothing on the server. GET and HEAD are safe. You can send them a hundred times and nothing happens to the data.
- An idempotent method has the same effect whether you send it once or ten times. GET, PUT and DELETE are idempotent: deleting order A-1001 twice still leaves it deleted; putting the same user twice leaves the same user. POST is not: sending "create an order" twice usually creates two orders.
This matters for testing — and for load testing especially. A load test sends a request thousands of times. Thousands of GETs are harmless; thousands of POSTs create thousands of records. It also matters when networks fail: if a POST times out, you don't know whether the order was created — sending it again might create a duplicate. Good APIs offer a way around this (an idempotency key), and good tests check it.
Putting it together
POST https://api.shop.example.com/v2/orders?notify=true
reads: at the shop API, version 2, create a new order, and send a notification. The details of the order travel in the body — next lesson.
Key takeaways
- The URL is the address: scheme, host, port, path and query. The base URL is the server; the path names the resource.
- The method says what to do: GET reads, POST creates, PUT replaces, PATCH changes part, DELETE removes.
- GET is safe (changes nothing) and POST isn't idempotent (sent twice, it acts twice) — remember both before you load-test.
In the app: The request bar · Choosing a base URL