A Look at REST API Design Patterns: Advanced
In this article, we'll take a look at some of the more advanced RESTful API design patterns/best practices.
Join the DZone community and get the full member experience.Join For Free
*This is a continuation of an earlier article on REST API design patterns found in my profile. Be sure to check that out as well.
Introduction: Design patterns are important, but often overlooked, aspect of the software design-and-development life cycle. In the last article on the subject, we reviewed some of the basic REST API design patters. In this one, let’s take a look at some of the more advanced design patterns in a RESTful API architecture.
Versioning: It is hard to write all APIs in one release, so avoiding versioning is not possible in many cases. The general rules of thumb we'd like to follow when versioning APIs are as follows:
- Upgrade the API to a new major version when the new implementation breaks the existing customer implementations
- Upgrade the API to a new minor version of the API when \
Types of Versioning
- Versioning through the URI path
The major and minor version changes can be a part of the URI, for example, to represent v1 or v2 of the API the URI can be http://localhost:9090/v1/books or http://localhost:9090/v2/books, respectively.
- Versioning through query parameters
The other simple method for implementing the version reference is to make it part of the request parameters.
- Versioning through custom headers
Define a new header that contains the version number in the request as part of request header itself. A custom header allows the client to maintain the same URIs, regardless of any version upgrades.
- Versioning through content-negotiation
Providing the version information through the Accept (request) header along with the content-type (media) in response is the preferred way as this helps to version APIs without any impact on the URI.
Authorization: Authorisation of users is a big topic in best practices for API designing.
1. Authorisation with the default key:
Using spring-security, we can easily secure our web APIs.
We can find very good documentation for spring security here
2. Authorisation with Credentials
In many real-time situations, we need to use specific credentials to access the API and not the default one.
Endpoint Redirection: Using standard HTTP return codes like 3xx, and with the Location header, then by receiving 301 Moved permanently or 307 Temporary Redirect, the service client can act get the redirection information.
The endpoint redirection pattern suggests returning standard HTTP headers and provides an automatic reference of stale endpoints to the current endpoints.
Hopefully, this article has shed more light on intuitive REST API design patterns, for anyone looking to delve a bit deeper. The enemy of design patterns are anti-patterns, which seem sound, but are counter-productive when executed. Unfortunately, anti-patterns are hard to detect.
Did you find this useful? Please leave a comment.
Opinions expressed by DZone contributors are their own.