API Architectural Styles

APIs are a significant piece of any software that uses the web. They're also incredibly important in SaaS as they provide consistency when systems need to be modular and scalable. 

APIs allow systems to access the functionality or functionality of another. They’re made up of specifications and/or protocols, known as the API architecture, that define what messages are sent and how those messages are structured.

There’s a lot of debate around which architectural style is the best, so we’re going to be discussing the four most commonly-used API architectural styles and what scenario they would best fit. 

A short overview of the four architectures

1. RPC (Remote Procedure Call)
   An RPC is a specification that makes the remote execution of a function in a different context possible.
   
   
2. SOAP (Simple Objects Access Protocol)
   A highly standardized web communication protocol that’s XML formatted.
   
   
3. REST (Representational State Transfer)
   An easy-to-understand style that’s defined by a set of constraints that was created with the intention of widespread adoption due to its self-explanatory nature.
   
   
4. GraphQL
   A syntax that describes how to precisely request data. 

The four architectures and their pros and cons

‍

1. RPC 

Pros

• Simple interactions: The RPC architecture uses POST for all tasks (except fetching information, which they use GET for). The interaction between a client and a server boils down to calling an endpoint and getting a reply.
  
  
• Functions are easy to add: If the API has a new requirement, then it’s easy to add another endpoint to execute it. All it takes is writing a new function and putting it behind an endpoint.
  
  
• High performance: RPC optimizes the network layer and makes it incredibly efficient, sending large amounts of messages between different services every day.
  
  

Cons

• Function overload: Since functions are so easy to create, there’s a tendency to avoid editing existing functions and instead just create new ones for the smallest of reasons.
  This leads to a huge number of functions that are hard to keep track of, hard to understand, and often overlap.
  
  
• Tight coupling with underlying system: RPC has a tight coupling with the underlying system, an abstraction layer between the system functions and external API isn’t possible. This raises a lot of security, scalability, and side effects issues.
  
  
• Low discoverability: There isn’t any way to introspect the API or figuring out which function to call based on its requests.
  
  

Use cases: An RPC is the right choice for sending commands to a remote system (such as Slack, which is very command-focused) as well as customer-specific APIS for internal microservices (think high message rates and performance, like gRPC and Twirp). 

2. SOAP –

Pros

• Bound to a number of transport protocols: Flexible when it comes to transfer protocols and can therefore accommodate a variety of scenarios.
  
  
• Platform and language agnostic: SOAP’s built-in ability to create web-based services means that it can handle communications and make responses independent of language and platform.
  
  
• Error-handling is built-in: SOAP’s specifications allow it to return the Retry XML message with an error code as well as its explanation.
  
  
• Variety of security extensions: SOAP is enterprise-grade transaction quality as it’s integrated with WS-security protocols. 

Cons

• XML only: SOAP messages have a lot of metadata and only support XML structures for requests and replies.
  
  
• Heavyweight: XML file sizes are huge, so SOAP services need a large bandwidth.
  
  
• Tedious message updating: Rigid SOAP schema slows down adoption as it’s difficult to edit message properties.
  
  
• Narrowly specialized knowledge: It takes in-depth knowledge of the protocols involved (and their restrictive rules) to build SOAP API servers.
  
  

Use cases: SOAP has s rigid structure and excellent security and authorization capabilities which make it best for highly secured data transmissions, e.g. financial organizations and other corporations. 

3. REST

Pros

• Supports multiple formats: Multiple formats for storing and exchanging data.
  
  
• Discoverable: No external documentation is needed to understand how to use the REST API.
  
  
• Cache-friendly: REST is the only style that allows data caching on the HTTP level. 

Cons

• No single REST structure: Which resources to model and how to do so depends entirely on each unique scenario.
  
  
• Large payloads: REST returns a lot of rich metadata and needs a big network pipe with a big bandwidth capacity.
  
  
• Overfetching and underfetching issues: REST responses can often contain either too much or not enough data, creating the need for another request. 

Use cases: Management APIS and simple, resource-driven apps are the best uses for REST. 

4. GraphQL

Pros

• Typed schema: GraphQL publishes what it can do in advance, making it more discoverable.
  
  
• No versioning: With GraphQL, the best versioning practice is not to version the API.
  
  
• Suited to graph-like data: This style is great for linked-relations data.
  
  
• Detailed error messages: Similar to SOAP, GraphQL provides details for errors that occur.
  
  
• Flexible permissions: It’s possible to selectively expose certain functions while preserving private information. 

Cons

• Performance issues: GraphQL cannot handle complex queries.
  
  
• Pre-development education needed
  
  
• Caching complexity: This style doesn’t reuse HTTP caching semantics, so it needs a custom caching effort. 

Use cases: GraphQL is an efficient data-loading option for mobile devices, and so is great for use is mobile APIs. Another great use for GraphQL is in complex systems and microservices, where GraphQL can hide the complexity of multiple systems behind its API.