A Beginner's Guide to HTTP and REST APIs

HTTP is the language the web speaks, and REST is a set of conventions for building APIs on top of it. If you understand a handful of core ideas, most APIs become easy to read and reason about.

The request/response cycle

Every HTTP interaction is a request from a client followed by a response from a server. A request has a method, a URL, headers, and sometimes a body:

GET /api/posts/42 HTTP/1.1
Host: api.example.com
Accept: application/json

The response includes a status code, headers, and a body:

HTTP/1.1 200 OK
Content-Type: application/json

{ "id": 42, "title": "Hello, HTTP" }

Methods and status codes

REST maps the common HTTP methods onto the idea of a resource:

• GET — read a resource.
• POST — create a resource.
• PUT / PATCH — update a resource.
• DELETE — remove a resource.

Status codes tell the client what happened. The ones you will see most often:

• 200 OK — success.
• 201 Created — a resource was created.
• 400 Bad Request — the client sent something invalid.
• 401 Unauthorized / 403 Forbidden — authentication or permission issues.
• 404 Not Found — the resource does not exist.
• 500 Internal Server Error — something broke server-side.

What makes an API “RESTful”

A REST API is organized around resources identified by URLs, manipulated with the standard methods, and ideally stateless — each request carries everything the server needs to understand it.

GET    /posts        -> list posts
GET    /posts/42     -> read one post
POST   /posts        -> create a post
PUT    /posts/42     -> replace a post
DELETE /posts/42     -> delete a post

A great API is boringly predictable. When resources, methods and status codes behave consistently, you rarely need to read the documentation twice.

Once these conventions click, you can pick up almost any JSON API in minutes rather than hours.