What is REST?
REST is primarily an architectural style, which means it provides a set of guidelines for designing networked applications. It is based on a stateless, client-server communication model, where clients make requests to servers to access and manipulate resources.
We call an API RESTful when it adheres to the principles of REST architecture. This includes using standard HTTP methods (GET, POST, PUT, DELETE), stateless communication, and resource-based URLs.
Contraints
There are six main constraints that define if an API is RESTful:
- Stateless: Each request from a client to a server must contain all the information needed to understand and process the request. The server does not store any client context between requests.
- Client-Server: The client and server are separate entities that communicate over a network. The client is responsible for the user interface, while the server manages data storage and processing.
- Uniform Interface: The API should have a consistent and standardized way of interacting with resources, this includes:
- Resource identification through URIs, e.g.,
/postsand/users/123 - Manipulation of resources through representations (e.g., JSON, XML)
- Self-descriptive messages (using standard HTTP methods and status codes)
- Hypermedia as the engine of application state (HATEOAS), where clients can navigate the API using links provided in responses.
- Resource identification through URIs, e.g.,
- Cacheable: Responses explicitly indicate if they can be cached (e.g., Cache-Control) to improve performance.
- Layered System: Requests may pass through multiple layers (load balancers, auth services, etc.) before reaching the API server, but to the client it appears as a single endpoint.
- Code on Demand (optional): Servers can provide executable code to clients, such as JavaScript, to enhance functionality. For example, a server could send a script that the client can run to validate user input.
Glossary
- URI (Uniform Resource Identifier): A string of characters used to identify a resource on the internet. It is often used interchangeably with URL (Uniform Resource Locator).
HTTP Basics for REST
Methods
The only HTTP methods you really need to know:
- GET: Retrieve data from the server. It should not modify any resources.
- POST: Create a new resource on the server.
- PUT: Update an existing resource or create a new one if it doesn’t exist.
- DELETE: Remove a resource from the server.
Status Codes
The only status codes you really need to know:
- 200 OK: The request was successful.
- 201 Created: A new resource has been successfully created.
- 204 No Content: The request was successful, but there is no content to return.
- 400 Bad Request: The server could not understand the request.
- 401 Unauthorized: The client must authenticate itself to get the requested response.
- 403 Forbidden: The client does not have access rights to the content.
- 404 Not Found: The server can not find the requested resource.
- 409 Conflict: The request could not be completed due to a conflict with the current state of the resource.
- 500 Internal Server Error: The server has encountered a situation it doesn’t know how to handle.
TIP
You should always aim for using the most appropriate combination of method and status code for each response. For a full (and fun) list of HTTP status codes, check HTTP Cats
Resources
In REST, a resource is any piece of information that can be identified and manipulated. Resources are typically represented as URLs.
For example, in a RESTful API for a blog, resources could include posts, comments, and users.
References
To be included:
- Versioning: Strategies for managing changes to the API over time.
- Authentication and Authorization: Methods for securing access to the API.
- Pagination: Techniques for handling large sets of data in API responses.
- Error Handling: Standardizing error responses for better client-server communication (with Python decorators).
- OpenAPI specifications.
- Caching strategies for REST APIs.