What Is a REST API? Principles, Methods, and Conventions

REST (Representational State Transfer) is an architectural style for building networked APIs, not a protocol or a standard with a spec you can go read end to end. It was defined by Roy Fielding in his 2000 doctoral dissertation as a description of the constraints that made the web itself work well at scale — most “REST APIs” in production today follow a practical subset of those ideas, not the full academic definition, and that’s fine.

The Core Idea: Resources

REST models everything as a resource — a user, an order, a document — each identified by a URL. Instead of an endpoint per action (/getUser, /updateUser, /deleteUser), REST uses one URL per resource (/users/42) and lets the HTTP method say what to do with it.

HTTP Methods

• GET — retrieve a resource. Safe (no side effects) and idempotent (calling it twice does nothing extra).
• POST — create a new resource, or trigger a non-idempotent action. Calling it twice can create two things.
• PUT — replace a resource entirely. Idempotent: sending the same PUT twice leaves the resource in the same state either time.
• PATCH — partially update a resource. Not necessarily idempotent, depending on what the patch actually describes.
• DELETE — remove a resource. Idempotent in the sense that deleting an already-deleted resource is still “gone” either way.

Status Codes That Actually Matter

A REST API communicates outcome through the HTTP status code, not just the response body:

• 2xx — success (200 OK, 201 Created, 204 No Content).
• 4xx — the client’s request was wrong somehow (400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 422 Unprocessable Entity).
• 5xx — the server failed to handle a valid request (500 Internal Server Error, 503 Service Unavailable).

Returning 200 OK with an error message in the body is a common but real anti-pattern — it breaks anything that inspects the status code to decide whether a request succeeded, including most HTTP client libraries’ default error handling.

Statelessness

Each request should carry everything the server needs to process it — the server doesn’t rely on session state left over from a previous request. This is why REST APIs typically send an auth credential on every single request rather than logging in once and relying on server memory.

Conventions Most Real APIs Follow

• Plural, noun-based paths: /users, not /getUsers.
• Nesting for relationships: /users/42/orders for one user’s orders.
• Pagination on list endpoints, via query params (?page=2&limit=50) or cursor-based tokens, so a collection with 100,000 items doesn’t come back in one response.
• Versioning, often in the URL (/v1/users) or a header, so breaking changes don’t break every existing client at once.

Testing REST APIs in HTTP Titan

REST is the default request type in HTTP Titan — pick a method, enter a URL, set headers/auth/body, and send it. Requests save into collections with folders that can mirror your API’s resource structure, and environment variables let the same request run against local, staging, and production without editing the URL by hand each time.