HTTP basics

HTTP is the set of rules that requests and responses follow on the web. Once you can read one request and one response, you can read them all.

A request has four parts

POST https://api.example.com/todos?notify=true
Content-Type: application/json
Authorization: Bearer abc123

{ "title": "Buy milk" }

Part	In the example	What it is
Method	POST	What you want done
URL	https://api.example.com/todos?notify=true	Where to send it
Headers	Content-Type, Authorization	Extra information about the request
Body	{ "title": "Buy milk" }	The data you are sending. Many requests have none

Methods: what you want done

Method	Meaning	Has a body?	Example
GET	Read something	Usually not	Get the list of todos
POST	Create something, or run an action	Yes	Add a todo, sign in
PUT	Replace something completely	Yes	Overwrite todo 5
PATCH	Change part of something	Yes	Mark todo 5 as done
DELETE	Remove something	Usually not	Delete todo 5
HEAD	Like GET, but only the headers come back	No	Check a file exists
OPTIONS	Ask what the server allows	No	Used by browsers before some requests

Two properties are worth knowing because tests rely on them:

• Safe methods (GET, HEAD, OPTIONS) only read. Sending one should never change anything.
• Idempotent methods (GET, PUT, DELETE) give the same result whether you send them once or five times. POST is not: send it twice and you may create two todos.

The URL: where it goes

https://api.example.com:443/todos/5?fields=title&done=false
└─┬─┘   └──────┬──────┘ └┬┘└──┬───┘ └──────────┬──────────┘
scheme       host      port  path          query string

• Scheme: https is encrypted, http is not. Use https for anything real.
• Host: which server. localhost means "this computer".
• Port: which door on that server. Left out, it is 443 for https and 80 for http. A mock on your machine might be at http://localhost:4010.
• Path: which endpoint. /todos/5 usually means "todo number 5". That 5 is a path parameter.
• Query string: options after the ?, as name=value pairs joined by &. These are query parameters.

A response has three parts

HTTP/1.1 201 Created
Content-Type: application/json
Location: /todos/101

{ "id": 101, "title": "Buy milk", "done": false }

A status code and its text, headers, and usually a body.

Status codes: how it went

The first digit tells you the kind of answer.

Range	Meaning	Who should act
2xx	It worked	Nobody
3xx	Look somewhere else (a redirect)	The client follows it
4xx	The request was wrong	The client: fix the request
5xx	The server failed	The server's owner

The ones you will see every day:

Code	Name	Typical meaning
200	OK	Success, with data in the body
201	Created	Success, and something new now exists
204	No Content	Success, and there is nothing to send back
301 / 302	Moved	The thing is at another URL
304	Not Modified	Your saved copy is still good
400	Bad Request	The server could not understand the request
401	Unauthorized	You did not say who you are, or the credentials are wrong
403	Forbidden	The server knows who you are, and you are not allowed
404	Not Found	Nothing exists at that URL
405	Method Not Allowed	The URL exists, but not for that method
409	Conflict	The request clashes with the current state
422	Unprocessable Content	The request was understood but a value is not acceptable
429	Too Many Requests	You are sending too fast. Slow down
500	Internal Server Error	The server hit a bug
502 / 503 / 504	Bad Gateway / Unavailable / Timeout	The server, or something in front of it, is down or overloaded

401 or 403?

401 means "who are you?" 403 means "I know who you are, and the answer is no." A good test suite checks that an API uses the right one.

Headers: the labels on the parcel

Headers are Name: value lines. Header names are not case-sensitive.

Header	Sent by	What it says
Content-Type	Both	The format of the body, such as application/json
Accept	Client	The formats the client would like back
Authorization	Client	Who the client is: a token or encoded credentials
User-Agent	Client	Which program is asking
Cookie / Set-Cookie	Client / server	Small values the server asks the client to keep and send back
Location	Server	Where the new or moved thing is
Cache-Control	Both	Whether the answer may be saved and reused
Retry-After	Server	How long to wait before trying again

The body: the data

A body can be any format. The Content-Type header says which.

Content-Type	Looks like	Used for
application/json	{"title": "Buy milk"}	Most modern APIs
application/x-www-form-urlencoded	title=Buy+milk&done=false	Simple web forms
multipart/form-data	Several parts, some of them files	Uploads
text/plain	Hello	Plain text
application/xml	<todo><title>Buy milk</title></todo>	Older and enterprise APIs

Where each part goes in ApiWorkbench

Part of the request	Where you set it
Method and URL	The bar at the top of the request
Query parameters and path variables	The Params tab
Headers	The Headers tab
Body	The Body tab
Credentials	The Auth tab

Part of the response	Where you read it
Status, time and size	The bar above the response
Body	The Pretty and Raw tabs
Headers	The Headers tab

See Build a request and Read the response for the details.

What you learned

• A request is a method, a URL, headers and an optional body.
• A response is a status code, headers and an optional body.
• 2xx worked, 4xx is the client's mistake, 5xx is the server's.

Next steps

• JSON basics: read the data in the body
• Your first API call: send a request yourself