REST
rest
Representational State Transfer: an architectural style for building web APIs using HTTP methods.
REST (Representational State Transfer) is the dominant architectural style for web APIs. RESTful APIs use standard HTTP methods (GET, POST, PUT, DELETE) to perform operations on resources identified by URLs. GET /users returns a list of users. GET /users/123 returns user 123. POST /users creates a new user.
REST works because it maps naturally to how the web already works. URLs identify things. HTTP methods describe actions on those things. Status codes (200 OK, 404 Not Found, 500 Server Error) communicate outcomes. Every web developer already understands these concepts.
Most APIs you encounter are REST APIs. They are simple to understand, easy to test (you can call them from a browser or curl), and well-supported by every programming language and framework. GraphQL is the main alternative.
Examples
A developer designs a REST API for a blog.
GET /posts returns all posts. GET /posts/42 returns post 42. POST /posts creates a new post. PUT /posts/42 updates post 42. DELETE /posts/42 deletes post 42. Each endpoint follows a predictable pattern. A developer who has used one endpoint can guess how the others work.
A REST API handles errors clearly.
A client sends GET /users/999 for a user that does not exist. The API returns 404 Not Found with a JSON body: {error: 'User not found', id: 999}. The status code tells the client what happened. The body gives details for debugging.
A REST API has versioning problems.
A company needs to change the response format of their /orders endpoint. They create /v2/orders with the new format while keeping /v1/orders working for existing customers. Customers get 12 months to migrate from v1 to v2.
In practice
Read more on the blog
Frequently asked questions
What is the difference between REST and GraphQL?
REST has fixed endpoints that return fixed data structures. GraphQL has a single endpoint where the client specifies exactly what data it wants. REST is simpler and more cacheable. GraphQL is more flexible and avoids over-fetching. Most companies start with REST and add GraphQL when they have complex data needs.
What does RESTful mean?
RESTful means an API follows REST principles: resources identified by URLs, operations mapped to HTTP methods, stateless requests (each request contains all needed information), and standard response codes. In practice, few APIs are purely RESTful. Most follow REST conventions loosely.
Related terms
Application programming interface: a defined way for software programs to communicate with each other.
A query language for APIs that lets clients request exactly the data they need.
An HTTP callback that sends data to your application automatically when an event occurs in another system.
A unique string that identifies and authenticates an application or user when making API requests.
Want the complete playbook?
Picks and Shovels is the definitive guide to developer marketing. Amazon #1 bestseller with practical strategies from 30 years of marketing to developers.