So much choice, when building a new API. Which architectural style should we choose for our cool new API? Are there any best practices regarding the architectural style for APIs?
But first, what is an architectural style? In general, an architectural style is a large-scale, predefined solution structure. There are architectural styles for pretty much anything, for example for building houses, for building software and for building APIs in particular. Using an architectural style helps us to design the solution quicker than designing everything from scratch.
Architectural styles provide predefined solution elements and are thus similar to design patterns or design templates. Whereas design patterns and templates are often used to solve local implementation issues, such as iterating through a list, architectural styles provide a solution for a larger challenge. The decision for an architectural style is far-reaching and permeates the complete solution.
The choice of architectural styles should be one of the first decisions when building a new API, as this is a decision that is hard to change later.
APIs can basically be realized using any of these architectural styles. How do we know, whether a particular style is appropriate for a given API? The resulting API exposes many desirable properties.
Sometimes there are trade-offs with other architectural demands. Good judgement has to be used to determine which demand wins. Examples of such competing architectural demands:
- Information abstraction
- Simplicity
- Loose coupling
- Network efficiency
- Resource granularity
- Convenience for the consumer
When should I use which Architectural Style for my API?
If you want more guidance regarding the question “When should I use which architectural style?” and look for some in-depth comparisons of the different architectural styles, then check out Chapter 5 on “API Proxy Architecture” in the API Architecture Book.
Best practice regarding Architectural Style for APIs
It is best practice to realize APIs using the REST architectural style. It is also the most common style. This is why one can assume in practice that APIs are realized with the REST style. Want to learn the REST-Style for API Design? Check out the RESTful API Design Book.
Also published on Medium.
