The Importance of API and Service Categorization

The main reasons to further categorize APIs and services is because of governance and ownership, as not all services and APIs are serving the same goal. An organization can have APIs to facilitate internal innovation within an organization, while others will help to automate business processes with external partners. An example of the latter can be an API that you make available to business partners to calculate a quote for the insurance products you are selling.

Not all APIs and services you define need to be governed in the same fashion, because some of them will serve a more tactical solution, while others will serve a strategic one.

When it comes to ownership not all services and APIs will be owned by the same team. Ownership of a service facilitating logging and monitoring purposes will be different then a service that supports your key business processes by the creation of customers in your customer management system.

We know the importance of making a distinction between different types of APIs and services, but how can we make that distinction properly? We want to avoid making a classification just to have a classification. The following characteristics will help you to find out to which service or API belongs to your organization.

• Level of Exposure: do we expose towards our own IT landscape, towards partners supporting our business processes or towards a public community that is not under our control.
• Purpose: does the service or API serve a single flow and consumer (single purpose) or has it been set up in a generic fashion so multiple consumers can use the data and functionality (multi purpose).
• Ownership: does the API or service serve a business purpose (business ownership), does it provide technical capabilities (IT ownership) or does it expose application data and functionality towards the IT landscape (application team ownership).
• Consumers: are the consumers applications, employees within our organization, business partners or the public community.

Based on the characteristics mentioned in the previous paragraph the following types of services and APIs can be identified:

• Public/Open API: APIs which are made publicly available by a company.
• Partner API: APIs offered towards all (current and future) partners of a company. This enables an automatic way of cooperation between company and partner (in an ecosystem).
• Private API: APIs offered towards the engagement systems of an enterprise. The objective is about making API’s usable for an optimal experience towards a number of engagement systems.
• Core Business service [*]: A service exposing generic data and/or functionality of a business domain, towards the rest of the IT landscape.
• B2B service: A service offered towards a specific partner of a company, tailored to the specific needs of the partner. This results in a different kind of governance compared to a partner API which is set up in a generic fashion to attract current and future partners.
• Utility service: A service exposing generic data and/or functionality towards the rest of the IT landscape, that does not belong to a specific business domain.
• System service [**]: Services offered by operational systems (e.g. software packages, legacy systems,…) which are not compliant to standards and/or guidelines within the company. The goal of a system service is to make data and functionality, encapsulated within the system, available to the rest of the IT landscape.
• Point to point integration: Integrations responsible for the connectivity between 2 or more application components. The data and functionality offered by the integration will not leave the application boundary.

Creating a service and API type classification is important so this can be incorporated within your organizations ‘integration reference architecture’. In this way it is clear for the projects which services and/or APIs can be identified and implemented.

You might think the classification is just a theoretical model but nothing could be further from the truth. By assigning the right classification to your API you will be able to define the right actions to be taken to come to a successful implementation.

Have you been taking functional design into account? Your public API, allowing partners to calculate a quote, will require a lot more design than a point to point integration as it will act as a window to your organization, just like your website does. To foster adoption you’d better be sure your partner API is easy to use and understandable by its consumers.

What about access control? Exposing data and functionality outside your companies’ boundary requires additional security measures to be taken compared to exposure within your organization.

Several governance aspects will be different for different types of APIs and services:

• Exposure of the partner quote API needs to be done through an API developer portal, while a business service shouldn’t.
• The frequency of change of a partner and public API needs to be kept low as you want your external consumers to offer a stable API. Point to point integrations can be more frequent to change because only the two application components integrating with each other will be impacted.
• The level of control, speed versus safety, can also be very different. Your time-to-market for APIs is typically much faster than business services supporting your core business processes.
• The classification also has an impact on your reference architecture: not all types of services and APIs need to have the same capabilities implemented. Depending on the required capabilities, different components need to be put in place.