This is the 1st part of a 3-part series on Designing REST APIs. You can check out the other parts here.
Most modern web applications expose APIs that clients can use to interact with the application.
A well-designed web API should aim to support:
- Platform independence
- Any client should be able to call the API, regardless of how the API is implemented internally.
- This requires using standard protocols, and having a mechanism whereby the client and the web service can agree on the format of the data to exchange.
- Service evolution
- The web API should be able to evolve and add functionality independently from client applications.
- As the API evolves, existing client applications should continue to function without modification.
- All functionality should be discoverable so that client applications can fully use it.
This guidance describes issues that you should consider when designing a web API.
Introduction to REST
REST is an architectural style like a design pattern for APIs. It follows a defined set of guidelines which helps make the APIs scalable, reliable, and predictable.
REST is not a technical rule. You can create non-REST APIs and they can get the job done. It is a guideline to be followed so that your applications are scalable and have predictable behavior.
REST is independent of any underlying protocol and is not necessarily tied to HTTP. However, most common REST implementations use HTTP as the application protocol, and this guide focuses on designing REST APIs for HTTP.
Here are some of the main design principles of RESTful APIs using HTTP:
- REST APIs are designed around resources, which are any kind of object, data, or service that can be accessed by the client.
- A resource has an identifier, which is a URI that uniquely identifies that resource.
- Clients interact with a service by exchanging representations of resources. Many web APIs use JSON as the exchange format.
- REST APIs use a uniform interface, which helps to decouple the client and service implementations. For REST APIs built on HTTP, the uniform interface includes using standard HTTP verbs to perform operations on resources. The most common operations are GET, POST, PUT, PATCH, and DELETE.
- REST APIs use a stateless request model.
- HTTP requests should be independent and may occur in any order, so keeping transient state information between requests is not feasible.
- The only place where information is stored is in the resources themselves, and each request should be an atomic operation.
- This constraint enables web services to be highly scalable because there is no need to retain any affinity between clients and specific servers. Any server can handle any request from any client.
- REST APIs are driven by hypermedia links that are contained in the representation. Read more at HATEOAS. This principle is rarely followed while building non-public APIs.
REST APIs - Best Practices
Use the following best practices to make your REST API easy to use, secure and performant:
- Use nouns to denote resources in URL instead of verbs. The action should be denoted by the HTTP method and not the URL.
- Collections should be plural so that it can be used to access a list and when appended with item id be used to denote a single item.
Example: /users - Heirarchical objects should be nested in the URL.
Example: /tweets/<tweet-id>/replies - Accept JSON for request payload and respond back with JSON payload. Set the correct Content-Type value in the response headers.
- Return proper HTTP Status Code.
- Return error object in response with a proper error message.
Example: {"error": "Invalid email address"} - Allow filtering, sorting and pagination through URL query parameters.
- Version the APIs to avoid breaking the clients consuming the APIs on changes in the contract.
- Add cache-related headers in response headers to let the client know if it needs to cache the response with details on when to invalidate the cache.
- Make sure to keep the APIs secure with access checks, encryption and follow the principle of least privilige.
Source: Docs from API design guidance - Best practices for cloud applications (with some modifications).
This is the 1st part of a 3-part series on Designing REST APIs. You can check out the second part here and the third part here.
