API Size Matters
The majority of APIs have ten paths or fewer
One-size-fits-all doesn't apply to APIs. Instead, they come in all kinds of shapes and sizes. Even if it's true that during design time people try to come up with small APIs, over time they tend to grow. By size, I'm referring to the number of paths that REST APIs have, and not any other measure like the number of parameters, or the length of the responses. So, what can you consider a "normal" size for an API?
This article is brought to you with the help of our supporters: Zuplo and Speakeasy.
Zuplo is the only API Gateway that runs your OpenAPI definition directly. If you care about high-quality developer documentation, API analytics, and zero configuration deployments, give Zuplo a try today.
Speakeasy provides you with the tools to craft truly developer-friendly integration experiences for your APIs: idiomatic, strongly typed, lightweight & customizable SDKs in 8+ languages, Terraform providers & always-in-sync docs. Increase API user adoption with friction-free integrations. Try Speakeasy now.
To get information about API size and trends, I analyzed over 4,000 APIs from APIs.guru. The list of APIs includes popular services like OpenAI, Slack, Stripe, and Twilio. What I found was that a majority of the APIs have ten paths or fewer, while larger APIs are distributed evenly according to the number of paths. I found it interesting that there are APIs with more than 1,000 paths. However, I preferred to treat those as outliers and stopped counting at 100 paths.
Managing large APIs
Why does API size matter? Let's first look at it from a security perspective. The more paths you expose—even if you only allow read operations—the larger the API's attack surface will be. An extensive attack surface increases the potential entry points for malicious actors attempting to exploit vulnerabilities. Also, numerous exposed endpoints increase the chances of inadvertently exposing sensitive information or providing unauthorized access to critical functionality. Other security-related factors also come into play, with a high number of exposed paths. Among those is the increased challenge with input validation. Because each path exposes operations with their own input requirements, ensuring the proper validation of all the operations becomes more challenging. Overall, a large amount of exposed paths increases the complexity of an API and its exposure to potential malicious attacks.
Another angle to consider is the one related to operations. It's clear to understand that as you increase the number of paths, managing and maintaining all the exposed endpoints can become more complex. Also, if the ownership of the whole API belongs to a single team, having a high number of operations results in a high development effort. If, on the other hand, you split the ownership of different paths among different teams, managing the shared maintenance becomes more difficult as the number of paths increase. However you look at it, the larger the API is, the more difficult it is to maintain.
Let's now look at it from a governance perspective. To begin with, having a large number of paths makes maintaining consistency crucial. Otherwise, you won't be able to guarantee clarity, usability, and uniformity across the API. From a lifecycle point of view, it becomes harder to modify existing paths or deprecate the ones that are no longer needed. Versioning also becomes more complex as the chance of introducing breaking changes increases.
Whatever angle you take, having a high number of paths makes things more complex and more difficult to manage. What happens to developers when they want to integrate with a large API?
Integrating with large APIs
Firstly, large APIs are inherently more difficult to understand. Developers face a steep learning curve when they start their process of integrating with a large API. They need to keep track of many endpoints and their purposes, and that can lead to errors during integration. An SDK can make things easier but, in this case, its size will also become problematic. By having to support a large number of endpoints, SDKs become complex to integrate with other systems and prone to failure.
From a support perspective, a large number of paths will result in increased difficulty in handling inquiries from consumers. Developers will find it hard to understand what goes wrong and obtain clear troubleshooting instructions when issues happen. In short, integrating with a large API creates uncertainty and can become a source of difficulties and increased development effort. And, what about low-code systems that offer your API to non-technical users?
Large APIs and AI
Low code systems, such as AI-powered chat user interfaces, can offer your API features to non-technical end users. Having a high number of paths makes it more difficult for end users to understand how to work with your API. That, in turn, makes your API less interesting for non-technical people to work with. All the developer-related issues I shared above are amplified when the consumer is a non-technical user.
Especially with AI systems, interacting with a large API becomes more complex. Systems such as ChatGPT expect your API to offer a clear functionality so it can be contextually picked whenever it makes sense. If you're offering a large amount of functionalities spread across different paths, AI systems will find it hard—if not impossible—to understand what exactly your API can do.
Summary
When does it make sense to have a large API? I can't think of any situation where an API with too many paths and operations is better than one with a simple and clear feature definition. Managing a large API is not an easy task and can create security, operational, and governance challenges. Integrating with a large API is difficult, error-prone, and generates a cognitive burden on engineering teams. Non-technical users find it non-trivial to work with large APIs. Making large APIs discoverable and easy to use within AI systems is complicated. These are some reasons why API size matters and why most APIs have ten paths or fewer.
Thank you for sharing. Very nicely written.