API Architectural Styles
Two separate application/system needs an intermediary to talk to each other and developers often build bridges — Application Programming Interface(API). The term “API” describes any interface that is exposed to offer services ( or using the specific protocol) in order to facilitate application development. They are not limited to any particular message format, pattern or implementation. Firstly, let’s look at desired properties of API before choosing architectural style.
Desired Properties of an API
- Consumer-Centric
- Simple
- Self-explanatory, Intuitive and Predictable
- Explorable and Discoverable
- Well-Documented
- Atomic
- Forgiving
- Secure and Compliant
- High performant, scalable and Available
- Interoperable and standards conform
- Reusable
- Backward -Compatible
These desired properties are to be considered from both perspectives of Consumer and Provider.
Which architectural style should we have for our API?
Are there any best practices regarding the architectural style for APIs?
Before that, what is an Architectural Style? It is a large scale, predefined solution structure. Design patterns or templates are used to solve the implementation issues, where as architecture styes provides a solution for a larger challenge. Thus, they are far-reaching and penetrates the complete solution. It helps to design the solution quicker than designing from scratch.
Choosing the architectural styles should be the first decisions when building an API.
- REST API Style
- gRPC API Style
- GraphQL API Style
- Falcor API Style
- RPC API Style
- SOAP API Style
There are trade-offs with our API architectural demands. Such architectural demands are
- Information abstraction
- Simplicity
- Loose Coupling
- Network efficiency
- Resource granularity
- Convenience of the consumer
Let’s review the each architectural style and understand the trade-off decisions.
REST API Style
REST (Representational State Transfer) is an architectural style and it defines a set of architectural constraints and agreements. An API which complied with the REST constraints are RESTful. The misconception is REST is not a standard or protocol. It is a style based on HTTP. It is best practice to realize APIs using the REST architectural style and is also the most common style originally described in 2000 by Roy Fielding.
REST imposes the following constraints :
- Use of HTTP capabilities as far as possible.
- Design of resources (nouns), not methods or operations(verbs)
- Use of the uniform interface defined by HTTP methods (POST, PUT, DELETE, GET, PATCH, etc..,)
- Stateless communication between client and server
- Use of loose coupling and independence of the requests
- Use of HTTP return codes
- Use of media-types
Pros
- Decoupled Client and Server
- Discoverability
- Cache-Friendly
- Multiple Formats support
Cons
- No single REST Structure
- Big Payloads
- Over-under fetching problems
Use cases
- Management APIs
- Simple resource driven apps
gRPC Style
gRPC follows the remote procedure pattern and allows for high performance implementations. It comes with a set of libraries that allow for an efficient implementation of an APIs. It is super fast and efficient as it uses protocol buffers to serialize/de-serialize the service and the message data into binary streams, HTTP standard for optimized binary transfers and bidirectional streaming to avoid polling and blocking HTTP calls.
Pros
- Straightforward and simple interaction
- Easy to add functions
- High performance
Cons
- Tight Coupling to the underlying system
- Low discoverability
- Function explosion
Use Cases
- Command API
- Customer-specific APIs for internal micro services
RPC API Style
RPC (Remote Procedure Call) is an API style for distributed systems. A Client invokes a remote procedure, serializes the parameters and additional information into a message, and sends the message to a server. The most widely used RPC styles: JSON-RPC and XML-RPC.
They do not need to run on the local machine, but they can run on a remote machine with the distributed system
GraphQL API Style
GraphQL is a data fetching language that allows clients to declarative describe their data requirements with a JSON like format. It is comparable to SQL, a database agnostic and allows to design with any kind of database. It gives control to consumer and possibility to describe their data needs. It optimizes the entire experience and solves many of the problems of the custom end-point approach.Thus, Customer-centric approach.
The capabilities of GraphQL are:
- It provides to describe the data served by the API with a rigorous type system. The space of accessible data is described as a type system in the Schema Definition Language (SDL)
- It provides to form complex queries over the data provided by the APO, including joins over different data types.
Pros
- Typed schema
- Fits graph-like data very well
- No versioning
- Detailed error messages
- Flexible permissions
Cons
- Performance issues
- Caching complexity
- A lot of pre-development education
Use cases
- Mobile API
- Complex systems and micro-services
Falcor API Style
It is an API style that is similar to GraphQL and introduces a virtual layer that can be used to map front end requests to back-end services. It is maintained by Netflix.
The basic idea of the Falcor API style is to create a visual JSON resource(published as URL address) as the central data model which actually used as a container. It links data from various back-ends and data sources into a virtual JSON resource.
SOAP API Style
It follows RPC API style and exposes procedures as central concepts and is standardized by the W3C. It is the most widely used protocol for web services.
Pros
- Language and Platform Agnostic
- Bound to a variety of transport protocols
- Built-in error handling
- A number of security extensions (ws-security protocols)
Cons
- XML only
- Heavyweight
- Narrowly Specialized Knowledge
- Tedious message updating
Use cases
- Highly secured data transmission
Conclusion
When it comes to Architectural Style, the best practice to build standard APIs is by using the REST architectural style. REST uses HTTP structure to facilitate communications and most widely used style. gRPC is catching up among architects and developers for its high performance and scalability. GraphQL and Falcor provides consumer-centric approach and custom API End-points. Every API has different requirements and needs. Usually, it depends on
- the programming language in use
- the environment in which you’re developing and
- the resources you have to spare, both human and financial
Which API style fits your use case best?
With its tight coupling, RPC & gRPC works for internal micro services but it’s not an option got a strong external or an API service. SOAP is troublesome but its rich security features remain irreplaceable for payments and booking systems. REST has the highest abstraction and best modelling But it tends to be heavier for mobile use cases. GraphQL is a big step forward in terms of data fetching but not much developers has enough time and effort to get the hand on it.
It makes sense to try a few small use cases with a particular style. If its fits your use case and solves problems, try expanding and see if its can fits more use cases as well.
I hope you got something out of this blog. If you found this post illuminating at all, consider sharing this post and following for more upcoming content.
