Many organizations have been looking at SOA (Service-Oriented Architecture) in the past to tackle and govern their integration challenges. One of the key aspects within a SOA landscape is the layering and classification of services. At Achers, we have seen many organizations each having their own way to classify their services. Some of them are based on the service layers defined by Thomas Erl, others are based upon a more technical approach like the service categorization defined by Oracle (Process, Activity, Data, Utility services).
The same questions show up at companies implementing an API program. They face the same challenges when it comes to API layering and classification, taking into account an already existing service classification.
In this blog post we will explain why API and service classification is needed and how this classification can be done.But First…
... let’s take a look at the differences between a service and an API.
- A service exposes data and functionality to the rest of an organizations' IT landscape, serving specific business needs.
- An API, within the context of API management, can be seen as a product the organization exposes towards its ecosystem of consumers that might be interested in using that APIs' data and functionalities. Unlike services, APIs are typically made available to a developer community by an API developer portal.
Why Do We Need to Categorize APIs and Services?
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.
Decisive Characteristics in Making a Distinction Between API and Services Types
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.
API and Services Types
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.
Consequences of Your Service & API Classification
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 has also 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.
With the rise of APIs, new challenges arise for organizations to give them a place within their existing IT landscape and position them on their integration architecture. In this blog we have been discussing why it is so important to pay enough attention to a good API and service classification and how such classification can be made. We discussed what kind of consequences such an API and service classification might bring to your organization.
You are now aware that making the right classification of your services and APIs is more than just giving them a name. Making the right classification will help your projects to make the right decisions and will help you to keep control over your service and API landscape.
Interested in sharing your insights with us, or interested in a partner that can help you tackle your API challenges? Don’t hesitate to contact us.
[*]: We don’t use the term “business service” as this can lead to confusion with the “business service” concept in the Archimate language.
[**]: We don’t use the term “application service” as this can lead to confusion with the “application service” concept used in the Archimate language.