REST Architecture and Principles

If you ask ten developers what REST is, you'll get ten slightly different answers — and most of those answers will be wrong in interesting ways. REST is not a protocol, not a library, not a framework. It's an architectural style for building web APIs, described by Roy Fielding in his 2000 PhD thesis and adopted (loosely, often imperfectly) by most modern web APIs since. Understanding what REST actually prescribes — and how often real APIs deviate — will make you a sharper API tester.

What REST stands for

REST = Representational State Transfer. Three words that look intimidating and turn out to mean something simple:

• Representational — clients work with representations of resources (usually JSON), not the resources themselves. The user record in your database is a row; the JSON you receive is a representation of that row.
• State Transfer — every request transfers some state between client and server: the data you read, the body you send, the response you get back.

Strip the academic phrasing and REST is just "expose your data as resources at predictable URLs and let clients act on them with HTTP verbs."

The five principles you should know

Client–server separation. The frontend and backend are independent. They communicate only via the API contract — which means each side can be replaced, refactored, or rewritten without breaking the other. As a tester, this gives you stable seams to test against.

Stateless requests. Each request must contain everything the server needs to process it. The server does not remember what you asked for last time. This sounds restrictive but is the reason APIs scale — any server in a load-balanced pool can handle any request. Authentication is included in every request (a token in a header), not held in a server-side session.

Cacheable. Responses can declare via headers (Cache-Control, ETag, Expires) whether they can be cached and for how long. Caching makes APIs faster and reduces server load — but it also means your tests must be careful about reading possibly-stale data after a write.

Uniform interface. All RESTful APIs feel similar: resources have predictable URLs, the same HTTP verbs mean the same things, response shapes follow recognisable patterns. Once you've tested two REST APIs you can navigate any new one quickly.

Layered system. A client doesn't know whether it's talking directly to the server or through a CDN, load balancer, API gateway, or three of each. As a tester, you may need to think about which layer is producing a confusing response.

Resources and URLs

In REST, everything is a resource — a thing with a stable URL. The URL is the resource's identity.

https://api.example.com/v1/users?role=admin&page=1

Break that down:

• https — protocol
• api.example.com — host
• /v1 — version (so you can release /v2 without breaking older clients)
• /users — the resource (a collection)
• ?role=admin&page=1 — query parameters (filters, paging)

Common URL patterns you'll meet again and again:

• /users — the collection of users.
• /users/123 — a specific user.
• /users/123/orders — orders belonging to user 123 (nested resource).
• /users/123/orders/456 — a specific order belonging to user 123.

Notice the pattern: collection → individual → sub-collection → individual. RESTful URLs are nouns arranged in a hierarchy.

Naming conventions

Style choices vary, but a few are widely accepted:

• Use nouns, not verbs. /users is RESTful; /getUsers is RPC-style and a smell.
• Use plural for collections. /users not /user. Even when there's only one user in the list, the collection is plural.
• Use lowercase with hyphens. /order-items reads more cleanly than /orderItems and is easier to type. Avoid /order_items (underscores look fine in code but are unusual in URLs).
• Express verbs through HTTP methods. Need to delete a user? DELETE /users/123, not POST /users/123/delete.

When you spot a URL with a verb in the path (/getUserById, /processPayment), the API is leaning RPC-style. That's fine to test — just don't expect the rest of the API to follow strict REST conventions either.

"RESTful" vs "REST-like"

Few real-world APIs are strictly RESTful — most break at least one principle. They might be:

• Stateful (a server-side session that breaks when load-balanced).
• Verb-y in their URLs.
• Inconsistent in error formats across endpoints.
• Missing pagination or caching headers.

That's reality, and it doesn't matter for testing. You test the API as it actually behaves, not as it claims to be. Read the docs, hit the endpoint, observe the response, write tests against what you see. Pure-REST religion is for blog posts; your job is correctness.

A useful mental shorthand: REST is a direction, not a destination. The closer an API gets to the principles, the easier it is to consume — but you'll work with plenty of "REST-ish" APIs and that's fine.

Why REST won

REST is dominant on the web for the same reason QWERTY keyboards are: not because it's perfect, but because everyone agrees on it. Tooling (curl, Postman, every HTTP client library), gateways (Cloudflare, AWS API Gateway), monitoring tools, OpenAPI specs, even REST cheat sheets all assume the REST style. Walk into a new team and the API will almost certainly be REST or GraphQL — knowing REST first pays off in nearly every job.

⚠️ Common mistakes

• Confusing REST with HTTP. HTTP is the transport. REST is one style of using HTTP. SOAP, GraphQL, and gRPC also use HTTP but follow different rules.
• Assuming REST APIs return JSON. Most do, but the spec doesn't require it — XML and even plain text are valid REST representations. Always check Content-Type.
• Insisting on "true REST". If the team's API uses POST /createUser, write the test as it stands and raise the convention question separately. Tests live in the present.

🎯 Practice task

Map a real API onto the REST principles. 20 minutes — no coding required.

1. Open the JSONPlaceholder docs. Skim the resource list (/posts, /users, /comments, /albums).
2. For each resource, write down its URL pattern in two forms: the collection (/posts) and the individual (/posts/1).
3. Spot the nested resource: /posts/1/comments returns comments belonging to post 1. What HTTP verb would you expect to retrieve it? What about creating a new comment?
4. Look at the GitHub REST API reference. Pick any endpoint and check whether the URL uses nouns, plurals, and lowercase. Note any deviations from strict REST conventions.
5. Stretch: find one endpoint in your own product (or any public API you use) that breaks a REST principle — a verb in the path, a non-cacheable GET, a stateful session. Write down which principle is broken and what test risk that creates.

You now know the architectural style behind most APIs you'll test. The next lesson dives into the building blocks every REST request uses: HTTP methods, status codes, and headers.