In this chapter, we will have a look at the main principles of a RESTful architecture. Then, with the help of very handy tools, we will design a friendly API, leveraging Jackson's capabilities to serialize our model in JSON.
We will document our application with the appropriate error codes and HTTP verbs and automatically generate a neat frontend for our application by using Swagger UI.
Finally, we will look at the other forms of serialization and learn more about the content negotiation mechanism of Spring MVC.
REST (Representational State Transfer) is an architectural style that defines best practices for creating scalable web services leveraging the capabilities of the HTTP protocol.
A RESTful web service should naturally exhibit the following properties:
- Client-server: The UI is separated from data storage
- Stateless: Each request contains enough information for the server to operate without maintaining any state
- Cacheable: The server's responses contain enough information to allow the clients to make sensible decisions about data storage
- Uniform interface: URIs uniquely identify resources and hyperlinks allow the API to be discovered
- Layered: Each resource of the API provides a sensible level of detail
The advantage of such an architecture is that it is simple to maintain and easy to discover. It also scales well because there is no need to maintain a persistent connection between the server and the client, which eliminates the need for load balancing or sticky sessions. Finally, the service is more efficient because the information is neatly laid out and easy to cache.
Let's see how we can design better APIs incrementally by using Richardson's maturity model.