In today’s issue, we will discuss the main API architectural styles, their usage, the pros and cons of each style, and recommendations for when to use each style.
Also, we will see the new OWASP Top 10 API security risks list, with additions and reasoning.
As a bonus, you will get an API Security Checklist to secure your APIs.
So, let’s dive in.
Various API architectural styles have emerged in web development and software integration to address different needs and use cases. When designing an API, the architectural style is crucial in determining its functionality, efficiency, and usability.
Here's a brief timeline of when these API styles emerged:
Here's an overview of the top 6 API architectural styles:
1. SOAP
SOAP is a protocol for exchanging structured information to implement web services. It was developed by Microsoft in 1998 as an evolution of XML-RPC. It uses XML for message format and relies on application layer protocols, primarily HTTP or SMTP, for message negotiation and transmission. Today, it’s mostly deprecated protocol found in legacy systems or systems where security is the most important.
➡️ An example usage of this protocol is that financial institutions might use SOAP for secure, transactional operations like transferring funds between accounts. Today, it is rarely used in new systems (mostly legacy).
✅ Pros:
Strong security and transactional capabilities
Platform and language-independent
Robust error handling and exception management
❌ Cons:
It is more complex and verbose compared to other styles
Slower performance due to XML overhead
Limited flexibility in data formats
2. REST
REST is a stateless architectural style that uses standard HTTP methods (GET, POST, PUT, DELETE). It is based on resources identified by a URL and supports various data formats, including JSON and XML. With its efficient use of standard HTTP methods, REST gained significant popularity in the mid-2000s with the rise of Web 2.0 and mobile applications. Today, it is a standard protocol for APIs, offering a reliable and efficient solution for many use cases.
➡️ An example of this format's usage could be a social media platform that uses a RESTful API to allow third-party applications to retrieve user posts.
And the response would be in JSON format:
✅ Pros:
Simple and easy to understand
Scalable and performant
Flexible in terms of data formats (JSON, XML, etc.)
❌ Cons:
Lack of clear contract or schema
Limited support for complex queries and operations
Inconsistent error handling using HTTP status codes
3. GraphQL
GraphQL is a query language for your API and a server-side runtime for executing queries using a type system you define for your data. It allows clients to request only the needed data, reducing the amount transferred over the network. Facebook developed it internally in 2012 and publicly released it in 2015.
➡️ An example of usage is in mobile apps to efficiently fetch product data, including only the fields they need for display.
✅ Pros:
Flexible and efficient data retrieval
Reduces the number of API requests
Enable clients to control the data they receive
❌ Cons:
Increased complexity in the server implementation
Potential performance issues with overly complex queries
Learning curve for both clients and server developers
4.gRPC
gRPC is a high-performance, open-source framework developed by Google that uses HTTP/2 for transport and Protocol Buffers (protobuf) as the interface description language. It provides authentication, load balancing, and other features. Google introduced it in 2015. gRPC was designed to meet the demands of modern microservices architectures, offering low latency and high throughput. It leverages HTTP/2 for multiplexing and efficient binary serialization via Protocol Buffers.
➡️ An example usage could be a real-time data processing system for efficient communication between its various microservices.
✅ Pros:
Great performance and low latency
Language-agnostic communication
Efficient data serialization and transport
❌ Cons:
Steeper learning curve compared to other styles
Limited browser support (requires additional tooling)
Tighter coupling between clients and servers
5. WebSocket
WebSocket protocol provides full-duplex communication channels over a single, long-lived connection, allowing real-time data transfer between a client and a server. Its real-time capabilities make it an exciting solution for applications that require instant data synchronization. It was developed to address the limitations of HTTP for real-time, bidirectional communication, which often relied on inefficient polling techniques.
➡️ An example of its usage is a real-time collaborative document editing application that might use WebSockets to synchronize changes between multiple users instantly.
✅ Pros:
Efficient for real-time applications (chat, gaming, live updates)
Reduced latency and overhead compared to traditional HTTP
Supports server-initiated data push
❌ Cons:
Requires specialized infrastructure and client-side support
Potential compatibility issues with older browsers and proxies
Increased complexity in error handling and fallback mechanisms
6. Webhooks
Webhooks are user-defined HTTP callbacks triggered by specific events. Unlike traditional APIs, where the client requests data, a webhook sends data to a client when an event occurs. This user-driven functionality makes webhooks a powerful tool for integrating systems and providing real-time notifications. Webhooks gained widespread adoption in the early 2010s as more services began to offer them to empower users to create their integrations and receive real-time notifications.
➡️ An example is when a payment processing service might use webhooks to notify an online web platform about the status of a transaction.
✅ Pros:
Simple and easy to implement
Scalable and asynchronous communication
Reduced polling and improved efficiency
❌ Cons:
Lack of clear contract or schema
Limited support for complex operations and error handling
Potential reliability issues due to the asynchronous nature
So, when to use each of these styles:
📌 Use SOAP when you need a highly standardized and secure API, especially for enterprise-level applications that require complex operations and robust error handling.
📌 Use REST for public APIs that prioritize simplicity, scalability, and flexibility, especially when dealing with stateless operations and standard web protocols.
📌 Use GraphQL when clients need to request specific data and control the structure of responses, making it ideal for applications with complex data requirements and fast prototyping.
📌 Use gRPC for high-performance, low-latency communication between microservices, especially when you need strong typing and efficient serialization.
📌 Use WebSocket for real-time, bidirectional communication in applications like chat or gaming, where low latency and immediate data exchange are crucial.
📌 Use Webhooks for event-driven architectures where you need to notify systems (such as payment confirmations or status updates) of changes asynchronously, allowing for efficient and scalable communication.
If you wonder when to use GraphQL, gRPC, or REST, check this text:
OWASP Top 10 API Security Risks
The well-known cybersecurity research group OWASP has revised its list of the top 10 hazards associated with unsecured APIs, known as the API Security Top 10. Launched in 2019, the API Security Project's 2023 update offers a more realistic picture of the dangers that application programming interfaces (APIs) face.
The new list, released in 2023, shows different types of auth flaws and new risks around business logic flows. Namely, they added three new risks:
✅ Unrestricted Access to Sensitive Business Flows - This risk implies that hackers could exploit non-technical weaknesses in business flows powered by APIs. Consider a customer who purchases every seat on an airline and then cancels their reservations for free at the last minute. The airline might then drastically increase prices to attract last-minute travelers, which would allow the hacker to buy a new ticket at a reduced price.
✅ Server-Side Request Forgery - This vulnerability dates back sometime and is included in the general OWASP Top 10. It was probably included in the list of APIs since SSRF is a more frequent attack vector and is frequently encountered, particularly in APIs.
✅ Unsafe Consumption of APIs - Developers frequently interact with third-party APIs and typically have high expectations for their results. However, this data may contain a wide variety of vulnerabilities. If it isn't cleaned up before being used in your services, it may cause serious problems.
❌ They also removed SQL Injection, which means that this style of attack on APIs has decreased.
Here is the complete list of the top 10 API security risks in 2023.
Broken Object-Level Authorization—APIs tend to expose endpoints that handle object identifiers, creating a broad attack surface of Object-Level Access Control issues.
Broken Authentication -Authentication mechanisms are often implemented incorrectly, allowing attackers to compromise authentication tokens or exploit implementation flaws to temporarily or permanently assume other users' identities.
Broken Object Property Level Authorization - The lack of or improper authorization validation at the object property level.
Unrestricted Resource Consumption - Satisfying API requests require network bandwidth, CPU, memory, and storage resources.
Broken Function-Level Authorization - Complex access control policies with hierarchies, groups, and roles and an unclear separation between administrative and regular functions tend to lead to authorization flaws.
Unrestricted Access to Sensitive Business Flows - APIs vulnerable to this risk expose a business flow - such as posting a comment - without compensating for how the functionality could harm the business if used excessively in an automated manner.
Server Side Request Forgery can occur when an API fetches a remote resource without validating the user-supplied URI.
Security Misconfiguration - APIs and the systems supporting them typically contain complex configurations meant to make the APIs more customizable.
Improper Inventory Management - APIs expose more endpoints than traditional web applications, making proper and updated documentation necessary.
Unsafe Consumption of APIs - Developers tend to trust data received from third-party APIs more than user input and, therefore, adopt weaker security standards.
BONUS: API Security Checklist
This checklist gives the most critical security countermeasures when designing, testing, and releasing your API in different categories, such as:
Authentication
Authorization
JWT
Access
CI & CD
And more.
More ways I can help you
Patreon Community: Join my community of engineers, managers, and software architects. You will get exclusive benefits, including all of my books and templates (worth 100$), early access to my content, insider news, helpful resources and tools, priority support, and the possibility to influence my work.
Sponsoring this newsletter will promote you to 33,000+ subscribers. It puts you in front of an audience of many engineering leaders and senior engineers who influence tech decisions and purchases.
1:1 Coaching: Book a working session with me. 1:1 coaching is available for personal and organizational/team growth topics. I help you become a high-performing leader 🚀.