REST API Basics

Why it matters

REST conventions let you predict the expected behaviour before you send a request: a create returns 201 Created, a deleted resource is no longer found, an unsupported method is refused with 405. Wherever an API breaks a convention without documenting it, client developers are likely to write code that handles it wrongly.

The cost of an API defect is multiplied by its clients. A renamed field or a 500 for bad input can break a web front end, a partner integration and app versions already installed on users' phones, none of which changed. Knowing the conventions turns "the API looks odd" into precise expectations for your test cases.

Resources, URIs, representations and statelessness

Fielding defines REST through six constraints, one of them optional, including statelessness and a uniform interface. APIs called REST often apply them only partly — hypermedia links that tell the client what it can do next are often left out — so judge an API by its own contract first and use REST conventions to spot inconsistencies. Four ideas matter most for testing:

• Resource: a named thing the API exposes — a task, a user, the list of tasks. Resources are nouns and the action comes from the method: POST /tasks, not POST /createTask.
• URI: the resource's identifier, with the syntax defined in RFC 3986. A common convention is a plural collection /tasks, its members /tasks/42 and sub-resources /tasks/42/comments.
• Representation: the resource's state in a concrete format. The client names the format it sends in Content-Type and the formats it can read in Accept.
• Statelessness: each request carries everything the server needs to understand it — credentials such as a token, identifiers, the page number. The server keeps no session context from earlier requests (the stored resources themselves of course remain), so a request can be repeated, sent on its own or handled by another server and still mean the same thing. Test it that way: request page 3 directly, without fetching pages 1 and 2 first.

Methods mapped to CRUD

CRUD — create, read, update, delete — names the basic operations on stored data. In REST each one is an HTTP method applied to the collection or to one item. You met the methods and their safe and idempotent properties in the lesson on HTTP methods; the table combines them with resources.

The pattern behind the table: you create on the collection, and the server chooses the new item's URI; you read the collection or one item; you update and delete one item at its own URI. Combinations outside the table — POST /tasks/42, or PUT, PATCH and DELETE on the whole collection — are usually not offered and should get 405 Method Not Allowed.

Operation  Method  URI          Typical success response
---------  ------  -----------  ---------------------------------------------
Create     POST    /tasks       201 Created + Location: /tasks/{id}
Read       GET     /tasks       200 OK, a list (often paged)
Read       GET     /tasks/{id}  200 OK, one task
Update     PUT     /tasks/{id}  200 OK or 204 No Content, whole task replaced
Update     PATCH   /tasks/{id}  200 OK or 204 No Content, sent fields only
Delete     DELETE  /tasks/{id}  204 No Content (200 with a body, 202 if queued)

Status codes in a REST API

Clients branch on the status code before they read the body, so the code is part of the contract. In REST it follows from the operation and the state of the resource, so every test case can state the expected code.

• 201 Created after a create, with a Location header holding the new URI (RFC 9110). A 200 with the id only in the body is a common deviation; the contract decides whether it is a defect.
• 204 No Content for a successful update or delete with nothing to return: the body must be empty.
• 404 Not Found for a missing item, including one just deleted. An empty list is 200 with an empty array.
• 405 Method Not Allowed for a method the resource does not support, with an Allow header listing the ones it does; RFC 9110 requires that header.
• 415 Unsupported Media Type for a body format the resource does not accept; 406 Not Acceptable when the server cannot produce any format listed in Accept — RFC 9110 also lets it send its default format instead.
• 409 Conflict when the request clashes with the current state, such as an e-mail that is already registered; 400 or 422 for invalid input, used consistently.
• Never 5xx for a client mistake: a 500 for bad input usually means input validation or error handling is missing.

Try it: HTTP Status Analyzer Try it: HTTP Status Code Lookup

Worked example: one task through its lifecycle

A tester walks one task through every operation, asserting the status code and the stored state after each step. The test account starts with no tasks.

• Later steps use /v1/tasks/57 from the Location header instead of a guessed URI.
• POST belongs to the collection: on the item /v1/tasks/57 it gets 405, and Allow lists the methods the item does support.
• After the DELETE the item is gone, so GET /v1/tasks/57 returns 404; the collection still exists, so GET /v1/tasks returns 200 with an empty array, not 404.
• Each method also keeps its own promises here — PATCH changes only the fields sent, PUT carries the complete state, and a repeated DELETE may return 404 and still be idempotent — as the sections on safe and idempotent methods and on what to test for each method in the lesson on HTTP methods explain.

POST /v1/tasks  {"title": "Pay rent", "done": false}
  -> 201 Created, Location: /v1/tasks/57
GET /v1/tasks/57
  -> 200 OK, {"id": 57, "title": "Pay rent", "done": false}
PATCH /v1/tasks/57  {"done": true}
  -> 200 OK, {"id": 57, "title": "Pay rent", "done": true}
POST /v1/tasks/57
  -> 405 Method Not Allowed, Allow: GET, HEAD, PUT, PATCH, DELETE
DELETE /v1/tasks/57
  -> 204 No Content
GET /v1/tasks/57
  -> 404 Not Found
GET /v1/tasks
  -> 200 OK, []

Try it: REST API Tester Try it: API Request Builder

Versioning and breaking changes

An API has clients its team does not control, so it cannot change freely. A breaking change makes a correct, unchanged client fail: removing or renaming a field, changing its type, making an optional request field required, or changing a URI or a status code. Adding an endpoint or an optional field is usually safe, provided clients ignore fields they do not know.

REST prescribes no versioning scheme. Teams choose one and document it in the contract, often an OpenAPI document: the URI path (/v1/tasks), a query parameter (?version=2), a custom request header such as Api-Version: 2 (the name varies by API) or the media type (Accept: application/vnd.example.v2+json).

• After a new version ships, run the old version's regression tests unchanged: v1 must still behave as its contract says.
• Send the same request to both versions and confirm that only the documented differences appear.
• Send no version, an unknown version and a retired one: expect the documented default or a clear 4xx, never a 500.

Try it: API Response Comparator Try it: OpenAPI Viewer

Frequently asked questions

References

• RFC 9110: HTTP SemanticsIETF · 2022The meaning of HTTP methods, header fields, status codes and content negotiation, independent of the wire version.
• RFC 3986: Uniform Resource Identifier (URI): Generic SyntaxIETF · 2005The parts of a URI (scheme, authority, path, query, fragment), reserved characters and percent-encoding.
• RFC 5789: PATCH Method for HTTPIETF · 2010The PATCH method for partial updates, as opposed to PUT replacing a whole resource.
• OpenAPI SpecificationOpenAPI InitiativeThe standard for describing REST APIs: paths, operations, parameters, schemas, responses and security schemes.