REST: The Architectural Style for Web APIs

WHY IT EXISTS Before REST, many APIs were custom-built, requiring unique logic for every client-server connection. REST was created as a set of architectural constraints to standardize how distributed systems, like the World Wide Web, should behave. It provides a common, predictable pattern for any client to communicate with any server, promoting scalability and independent development.

THE MENTAL MODEL Think of REST as the grammar for the language of HTTP. It's not a protocol itself but a style guide that defines how to structure requests and responses. The core idea is to treat everything on the server as a 'resource' (like a user or a product). The client then requests a 'representation' of that resource's state, typically as a JSON object, and can perform actions on it.

HOW IT WORKS REST combines several principles. First, resources are identified by unique URLs (e.g., /users/123). Second, you use standard HTTP methods as verbs to act on these resources: GET to retrieve, POST to create, PUT to update, and DELETE to remove. This creates a uniform interface. Third, communication is stateless; every request from the client must contain all information needed to process it, which helps scalability. Finally, the server's response (the representation) can be cached by clients or intermediaries to reduce latency.

WHEN TO USE IT REST is the default choice for most public-facing APIs and client-server communication in web and mobile apps. Its reliance on standard HTTP makes it easy to implement and consume across different platforms. It excels in systems where you need to separate the client and server, allowing them to evolve independently, and where scalability and caching are important.

WHEN NOT TO USE IT REST is less ideal for services that require a persistent, two-way connection, like a real-time chat app; WebSockets are better suited for that. It can also be inefficient for complex data needs where clients require very specific fields, which can lead to over-fetching. In those cases, an alternative like GraphQL might be a better fit.

ONE CANONICAL EXAMPLE Imagine a simple API for blog posts. To get a list of all posts, you would make a GET request to /posts. To retrieve a single post with ID 42, you'd use GET /posts/42. To create a new post, you'd send a POST request to /posts with the post data in the request body. To delete post 42, you'd send a DELETE request to /posts/42. This pattern is predictable and easy to understand.