The Impact of a Large Number of API Features
Can the amount of API features be related to the success of a business?
Is it better to have a small or a large number of API features? And, what is an API feature, anyway? Follow me while I explore the ins and outs of how the amount of API features can impact different areas of the business.
This article is brought to you with the help of our supporter: Speakeasy.
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.
API features are what customers interact with when building integrations with your product. API features are usually exposed at a high level in the path hierarchy. They're easy to identify and simple to understand. API features are "first citizens" of the product and constitute big bets from a business perspective.
An example is Stripe's "Customers" feature. It's exposed to the product at a high level, offers specific capabilities related to customers, and lets users perform very specific tasks. On the Stripe API, this feature can be translated to the /v1/customers base path and all the subpaths within.
Stripe is a company with thousands of engineers that offers an API with a total of 66 high-level features. Shopify follows a similar path with an API having 77 features. Jira is another example, providing 65 features through its API.
What these APIs have in common are two things. First, they all have a relatively high number of exposed features. The other common thing these APIs have is the very high total number of operations. Stripe and Jira have 498 and 499 operations respectively and Shopify exposes a total of 1470 operations. While both Stripe and Jira have an average of eight operations per feature, Shopify's ratio of operations per feature is 19.
What do these numbers mean? Before answering let's look at examples of APIs that don't follow the same trends. OpenAI, for instance, has just 11 features with a total of 51 operations. Postman exposes 22 features that translate into 139 operations. Finally, Vercel offers 16 features exposing 111 operations.
The anatomy of these APIs shows there's a relatively small number of entry points—the features—followed by all the operations that provide the individual capabilities. All three APIs have a ratio of operations per feature below 10, meaning that each feature isn't overloaded with capabilities.
So, how can this disparity in the number of features impact the business? If each feature constitutes a first-class citizen part of the product, then its importance is quite high in the business. One thing to notice is how the features are probably aligned with the hierarchy of each company. Conway's Law states that "organizations which design systems are constrained to produce designs which are copies of the communication structures of these organizations."
In other words, there's a high chance each one of the API features has a specific team—or company division—behind it. In the case of OpenAI, you could imagine a team working on images, another one on threads, and another team assigned to assistants.
As the number of features increases, you only have the options of overloading existing teams or creating more teams to manage those features. In cases such as Shopify, having 77 high-level features means there's probably a similar number of teams in the structure of the company.
Let's now look at how the amount of API features can also influence the Developer Experience. As the number of features grows so does the complexity of learning how to use the API. Factors that contribute to a steep learning curve include difficulty in discovering how the features work and complexity in understanding how to build integrations for specific use cases.
From the perspective of the API producer, an increase in the number of features increases the complexity of providing good support, complications in generating and maintaining high-quality SDKs, and difficulty in producing documentation that reflects what the API can offer.
The impact of these factors on the success of a business has to do with how a decrease in perceived quality translates into more costs, less revenue, or both. As I wrote before, you can influence business growth by reducing the cost of API support and increasing retention.
A low number of API features makes support easier to handle potentially leading to a lower cost. Additionally, good documentation with clear and targeted information can further reduce the cost of support as fewer consumers will need it during their interactions with the API. Finally, offering a simple-to-use set of features makes the API less prone to errors, which again decreases the need consumers have to engage with support.
To increase retention you need to improve the Developer Experience. The best way to do that is to reduce the API friction, making sure the following don't happen:
Difficulty in understanding what the API is: a small number of features makes it easier to understand the API.
Difficulty in experimenting with the API: it's easier to test the API to see what it does if it has a small amount of features.
Lack of SDKs: As the number of features increases so does the difficulty in maintaining an SDK.
Too much work needed: a high number of features leads to a high complexity in building an integration.
Overall I believe having a large number of features contributes to a decrease in the quality of the API and will see reflections in the performance of the business.
So, how do companies like Stripe, Shopify, and Atlassian (the company behind Jira) manage to have positive business results?
One answer is that the features they offer as high-level API subpaths aren't necessarily reflected on the product. They treat their APIs more as a programming tool and not so much as a mirror of the product itself.
Another answer is they all excel at providing fantastic developer documentation. In fact, I'd say they make a huge investment in that area to attract and keep developers engaged.
Finally, they also offer customized SDKs for specific use cases and scenarios. These companies take pride in owning different SDKs and integration tools enabling developers to easily build on top of various systems.
However, to be able to follow the steps of Stripe, Shopify, and Atlassian you would need to have their resources. If you don't, then handling a small number of API features makes things easier for both you—the API producer—and all the consumers you want to work with.