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) or http (not encrypted). Real APIs should use https; http is fine on your own computer.
  • Host — which server: api.shop.example.com. On your own computer it's localhost or 127.0.0.1.
  • Port — which "door" on that server. Usually left out: https means 443 and http means 80. Programs you run yourself often use others, like localhost:3000 or localhost: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 ?, as name=value pairs 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:

PathMeans
/ordersall orders (a collection)
/orders/A-1001one order
/orders/A-1001/itemsthe items of that order
/users/42/ordersthe orders of user 42

The method then says what to do with it.

The method: what to do

MethodMeansExampleHas a body?
GETRead — give me thisGET /orders/A-1001No
POSTCreate — make a new one (or do something)POST /orders with the new orderYes
PUTReplace — make this one exactly like thisPUT /users/42 with the whole userYes
PATCHChange part of itPATCH /users/42 with just { "email": "…" }Yes
DELETERemove itDELETE /orders/A-1001Usually no
HEADLike GET, but only the headers — does it exist, how big is it?No
OPTIONSWhat 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

Next: Headers, query parameters and bodies

A question these lessons don’t answer? Write to support@apitestcenter.com — we add lessons for the questions people ask.