REST APIs

A common, predictable way to structure requests so different apps can talk to a server the same way.

What is it?

An API (Application Programming Interface) is simply a way one piece of software lets another piece of software ask it to do things. But an API could be organized in a thousand different, inconsistent ways — which makes it hard to learn and use. REST (Representational State Transfer) is a popular, widely-agreed-upon style for designing APIs so that they're consistent and predictable across countless different services.

The core idea: everything is a "resource" (like a user, a post, a product), identified by a URL, and you use standard HTTP methods to act on it — GET to read, POST to create, PUT/PATCH to update, DELETE to remove.

Explain like I'm 10

REST is like a well-labeled filing cabinet where every drawer follows the same layout convention, and every drawer lets you do the same standard set of things — look inside, add a paper, replace its contents, or remove it. Once you understand one drawer, you instantly know how to work with any other drawer in any cabinet built the same way.

Examples

REST-style endpoints for a 'posts' resource

GET    /posts       // get all posts
GET    /posts/42    // get one specific post
POST   /posts       // create a new post
PUT    /posts/42    // replace post 42 entirely
PATCH  /posts/42    // partially update post 42
DELETE /posts/42    // delete post 42

Notice the URL identifies what you're acting on (a post, or a specific one), and the HTTP method identifies what action you're taking.

How it works

A REST API exposes resources as URLs and relies on standard HTTP methods and status codes rather than inventing custom verbs for every action. This consistency means a developer who's used one REST API can usually guess how another one works, without reading extensive documentation.

Why does it exist?

Before conventions like REST became common, every API had its own bespoke rules, making integration slow and error-prone. REST gives teams a shared set of conventions, which speeds up building and consuming APIs across completely different companies and codebases.

When to use it

Reach for REST conventions when you're designing a general-purpose API for resources (users, posts, products) that other developers — possibly outside your team — will need to learn and use.

When not to use it

For very specific, action-oriented operations that don't map cleanly to a resource (like "run this report" or "send this batch job"), forcing a REST shape can feel awkward — an RPC-style or GraphQL API sometimes fits better.

Common mistakes

  • Using verbs in URLs (/getUser) instead of nouns with proper HTTP methods (GET /user).

  • Returning 200 OK for every response, even for errors, instead of using proper status codes.

  • Designing endpoints that don't map cleanly to a resource, making the API inconsistent and confusing.

Practice exercises

  1. Easy:

    Design REST-style endpoints for a 'comments' resource: list, get one, create, update, delete.

  2. Medium:

    Explain why POST /users/delete/42 is not a RESTful way to delete a user, and rewrite it properly.

  3. Hard:

    Design a small REST API (endpoints + methods + expected status codes) for a simple to-do list app.

Interview questions

What does REST stand for, and what's its core idea?

Representational State Transfer — the core idea is treating everything as a resource identified by a URL, manipulated using standard HTTP methods.

What makes an API 'RESTful'?

Using resource-based URLs, standard HTTP methods for actions, standard status codes for outcomes, and being stateless between requests.

What's the difference between PUT and PATCH?

PUT typically replaces an entire resource; PATCH applies a partial update, changing only the specified fields.

What's the difference between a resource and an endpoint in a REST API?

A resource is the conceptual thing being represented (e.g. 'a user'); an endpoint is the specific URL through which clients access or act on that resource (e.g. /users/42) — one resource can be reachable through more than one endpoint, such as a nested and a top-level route.

Why should REST URLs use nouns for resources rather than verbs for actions?

The HTTP method already expresses the action (GET, POST, PUT, DELETE); putting a verb in the URL too (like /deleteUser) duplicates and can conflict with that, and makes the API inconsistent since every developer might phrase actions differently.

What status code should a successful POST that creates a new resource return, and what else is commonly included?

201 Created, typically along with a Location header pointing to the URL of the newly created resource, so the client knows where to find or reference it afterward.

What status code fits a successful DELETE that returns no response body?

204 No Content — it confirms success without implying there's any data to read in the response body.

Why is statelessness considered a defining constraint of REST rather than just a nice-to-have?

REST requires that each request contain everything needed to process it, with no reliance on server-side session state between requests — this is what lets any server instance handle any request, which is essential for horizontal scaling and simple load balancing.

What's the difference between a REST-style API and an RPC-style API?

REST models everything as resources manipulated through a small, standard set of HTTP methods; RPC exposes specific named actions/procedures directly (e.g. POST /createUser, POST /banUser), which can be more flexible for arbitrary operations but loses REST's uniform, predictable structure.

What's the difference between REST and GraphQL, and when might GraphQL be a better fit?

REST exposes fixed endpoints that each return a predetermined shape of data; GraphQL exposes a single endpoint where the client specifies exactly which fields it needs — GraphQL tends to fit better when clients have very different, evolving data needs and over- or under-fetching from REST endpoints becomes a real problem.

What does HATEOAS mean, and why do most real-world 'REST' APIs skip it?

Hypermedia As The Engine Of Application State — the idea that a response includes links describing what actions or resources are available next, so clients don't need to hardcode URL structures. Most APIs skip it because it adds real implementation complexity for a benefit (loosely coupled clients) that most consumers don't end up needing in practice.

Name a couple of common approaches to versioning a REST API.

Putting the version in the URL path (e.g. /v1/users), or in a request header (e.g. Accept: application/vnd.myapi.v1+json) — URL versioning is simpler and more visible, while header versioning keeps URLs stable but is less discoverable.

When is nesting resources in a URL (e.g. /users/1/posts) useful, and when does it become an anti-pattern?

It's useful when a resource is genuinely scoped to its parent (posts that only make sense in the context of a user); it becomes awkward when nesting goes several levels deep or when the same resource needs to be reached both independently and through a parent, leading to duplicate or inconsistent routes.

How should a REST API represent pagination for a large collection?

Typically via query parameters (like ?page=2&limit=20 or a cursor-based ?after=<id>), with metadata in the response (or headers/links) indicating total count or how to fetch the next page, rather than returning the entire collection in one response.

What's the difference between filtering, sorting, and pagination as REST query parameters?

Filtering narrows down which items in a collection are returned (e.g. ?status=active); sorting controls the order of the returned items (e.g. ?sort=-createdAt); pagination controls how many items and which subset are returned at once — the three are typically combined but are conceptually independent.

Why should a REST API generally avoid exposing raw internal database ids or implementation details in its responses?

It couples clients to internal storage decisions that should be free to change (e.g. switching database or id scheme), and can leak information (like sequential ids revealing record counts) that clients don't need and shouldn't depend on.

Is a REST API required to return JSON? What does the word "representational" in REST actually refer to?

No — REST is format-agnostic; JSON is just the most common convention today. "Representational" refers to the idea that clients interact with a representation of a resource's state (in whatever format, JSON, XML, or otherwise), not the resource itself.

How should a REST API communicate a validation error to the client?

With a 4xx status code (typically 400 Bad Request or 422 Unprocessable Entity) and a response body describing which fields failed validation and why, so the client can surface something actionable rather than a generic failure.

What's an idempotency key, and why might a REST API need one for a POST request?

A client-generated unique value sent with a request so that if the same request is retried (e.g. after a timeout, without the client knowing whether the first attempt succeeded), the server can recognize the duplicate and avoid performing the action twice — commonly used for things like payments, where POST's natural non-idempotency is dangerous.

Why is caching often easier to reason about in REST than in RPC-based or GraphQL APIs?

REST's use of GET on stable resource URLs maps naturally onto standard HTTP caching (by URL); RPC and GraphQL typically funnel varied requests through a single endpoint (often via POST), which doesn't get cached the same way by browsers, proxies, or CDNs without extra custom logic.

Why does it help for a REST API's error responses to follow one consistent structure across all endpoints?

A predictable error shape (e.g. always including a code, message, and optional field-level details) lets client code handle errors generically instead of writing custom parsing per endpoint, and makes API documentation and debugging far more consistent.

Why is over-fetching or under-fetching a common criticism of REST APIs, and how does it come about?

Because a REST endpoint returns a fixed shape of data, a client that needs only a couple of fields still receives the whole resource (over-fetching), while a client that needs data from multiple resources often has to make several separate requests (under-fetching) — both waste bandwidth or round trips compared to a query that could ask for exactly what's needed.

What does it mean for a REST API to be "resource-oriented," and how does that shape its URL design?

It means the API is organized around nouns representing things in the domain (users, orders, posts) rather than around actions — which forces URL design toward /resource and /resource/:id patterns manipulated by standard HTTP methods, instead of an ever-growing list of custom action endpoints.

How would you design an endpoint to update just one field of a resource, and which HTTP method fits best?

PATCH /resource/:id with a body containing only the field(s) to change (e.g. { status: "archived" }) — PATCH is the right method because it's defined for partial updates, unlike PUT, which implies replacing the whole resource.

Why is it considered bad practice for an API to always return 200 OK, even for errors?

It forces every client to parse the response body just to find out whether the request actually succeeded, defeating the purpose of standard status codes, and breaks tooling (like HTTP caches, monitoring, and generic error handling) that relies on the status code reflecting the real outcome.