[The API Product] API Services Range

This is a new chapter for the future Section III ‘The API Product’ of the API book I’m currently writing. I’d appreciate if you share it on reddit, for I personally can’t do that.

The important rule of API product management that any major API provider will soon learn formulates like that: there is no sense to ship one specific API; there is always a room for a range of products, and this range is two-dimensional.

Horizontal scaling of API services

Usually, any functionality available through an API might be split into independent units. For example, in our coffee API, there are offer search endpoints and order processing endpoints. Nothing could prevent us from either pronouncing those functional clusters different APIs or, vice versa, considering them as parts of one API.

Different companies employ different approaches to determining the granularity of API services, what is counted as a separate product and what is not. To some extent, this is a matter of convenience and taste judgment. Consider splitting an API into parts if:

• it makes sense for partners to integrate only one API part, e.g. some isolated subset of the API provides enough means to solve users’ problems;
• API parts might be versioned separately and independently, and it is meaningful from the partners’ point of view (this usually means that those ‘isolated’ APIs are either fully independent or maintain strict backwards compatibility and introduce new major versions only when it’s absolutely necessary; otherwise, maintaining a matrix which API №1 version is compatible with which API №2 version will soon become a catastrophe);
• it makes sense to set tariffs and limits for each API service independently;
• the auditory of the API segments (either developers, business owners, or end users) is not overlapping, and ‘selling’ granular API to customers is much easier than aggregated.

NB: still, those split APIs might still be a part of a united SDK, to make programmer’s life easier.

Vertical scaling of API services

However, frequently it makes sense to provide several API services manipulating the same functionality. The thing is that the fragmentation of API customers across their professional skill levels results in several important implications:

• it’s almost impossible in a course of a single product to create an API that will fit well both amateur developers and professional ones: the former need the maximum simplicity of implementing basic use cases, while the latter seek the ability to adapt the API to match technological stack and development paradigms, and the problems they solve usually require deep customization;
• the huge share of customers’ inquiries to your customer support service will be generated by the first category of developers: it’s much harder for amateurs or beginners to find answers to their questions by themselves, and they will address them to you;
• at the same time, the second category is much more sensitive to the quality of both the product and customer support, and fulfilling their requests might be non-trivial.

The most important conclusion here is that the only way to cover the needs of all categories of customers is to develop a range of products with different entry thresholds and requirements for developers’ professional level. We might name several API sub-types, ordered from the most technically demanding to less complex ones.

1. The most advanced level is that of physical APIs and the abstractions on top of them. [In our coffee example, the collection of entities describing working with APIs of physical coffee machines, see Chapter 9 and Chapter 17.]
2. The basic level of working with product entities via formal interfaces. [In our study example, that will be HTTP API for making orders.]
3. Working with product entities might be simplified if SDKs are provided for some popular platforms that tailor API concepts according to the paradigms of those platforms (for those developers who are proficient with specific platforms only that will save a lot of effort on dealing with formal protocols and interfaces).
4. The next simplification step is providing services for code generation. In this service, developers choose one of the pre-built integration templates, customize some options, and got a ready-to-use piece of code that might be simply copy-pasted into the application code (and might be additionally customized by adding some level 1–3 code). This approach is sometimes called ‘point-and-click programming’. [In the case of our coffee API, an example of such a service might have a form or screen editor for a developer to place UI elements and get the working application code.]
5. Finally, this approach might be simplified even further if the service generates not code but a ready-to-use component / widget / frame and a one-liner to integrate it. [For example, if we allow embedding an iframe that handles the entire coffee ordering process right on the partner’s website, or describes the rules of forming the image URL that will show the most relevant offer to an end user if embedded in the partner’s app.]

Ultimately, we will end up with a concept of meta-API, e.g. those high-level components will have an API of their own built on top of the basic API.

The most important advantage of having a range of APIs is not only about adapting it to the developer’s capabilities, but also about increasing the level of control you have over the code that partners embed into their apps.

1. The apps that use physical interfaces are out of your control; for example, you can’t force switching to newer versions of the platform or, let’s say, add commercial inlets to them.
2. The apps that operate base APIs will let you manipulate underlying abstraction levels — move to newer technologies or alter the way search results are presented to an end user.
3. SDKs, especially those proving UI components, provide a higher degree of control over the look and feel of partners’ applications, which allows you to evolve the UI, adding new interactive elements and enriching the functionality of existing ones. [For example, if our coffee SDK contains the map of coffee shops, nothing could stop us from making map objects clickable in the next API version or highlighting paid offerings.]
4. Code generation makes it possible to manipulate the desired form of integrations. For example, if our KPI is a number of searches performed through the API, we might alter the generated code so it will show the search panel in the most convenient position in the app; as partners using code-generation services rarely make any changes in the resulting code, this will help you in reaching the goal.
5. Finally, ready-to-use components and widgets are under your full control, and you might experiment with functionality exposed through them in partners’ applications just like if it was your own service. (However, it doesn’t automatically mean that you might draw some profits from having this control; for example, if you’re allowing inserting pictures by their direct URL, your control over this integration is rather negligible, so it’s generally better to provide those kinds of integration that allow having more control over the functionality in partners’ apps.)

NB. While developing a ‘vertical’ range of APIs, following the principles stated in the Chapter 14 ‘On the Iceberg’s Waterline’ is crucial. You might manipulate widget content and behavior if, and only if, developers can’t ‘escape the sandbox’, e.g. have direct access to low-level objects encapsulated within the widget.

In general, you should aim to have each partner service using the API service that maximizes your profit as an API vendor. Where the partner doesn’t try to make some unique experience and needs just a typical solution, you would benefit from making them use widgets, which are under your full control and thus ease the API version fragmentation problem and allow for experimenting in order to reach your KPIs. Where the partner possesses some unique expertise in the subject area and develops a unique service on top of your API, you would benefit from allowing full freedom in customizing the integration, so they might cover specific market niches and enjoy the advantage of offering more flexibility compared to using other APIs.