Types of APIs and how to determine which to build

It’s rare that an organization decides it needs an API out of the blue — most often, organizations start with an idea, application, innovation, or use case that requires connectivity to other systems or datasets.

APIs come into the picture as a means of enabling connectivity between the systems and datasets that need to be integrated.

Organizations may use different types of APIs for different purposes: from exposing a core system's functionality internally, to enabling a customer-facing mobile app. MuleSoft's API-led connectivity approach includes three categories of APIs:

• System APIs: System APIs unlock data from core systems of record within an organization. Examples of critical systems that APIs could unlock data from include ERP, customer and billing systems, and proprietary databases.
• Process APIs: Process APIs interact with and shape data within a single system or across systems — breaking down data silos. Process APIs provide a means of combining data and orchestrating multiple System APIs for a specific business purpose. Examples of this include creating a 360-degree view of the customer, order fulfillment, and shipment status.
• Experience APIs: Experience APIs provide a business context for the data and processes that were unlocked and established with System and Process APIs. Experience APIs expose the data to be consumed by its intended audience — such as mobile applications, internal portals for customer data, etc.

Once you’ve determined the use case for your organization’s APIs, it’s time to determine who will be accessing these APIs. Most often the use case and the intended user go hand-in-hand — for example, you may want to surface customer data for your internal sales and service agents, the intended end-user, in this case, is internal employees.

Below are three types of APIs based on how they are managed and who they are accessed by:

External APIs can be accessed by third-parties (developers, partners, etc.) that are external to the organization. They often make an organization's data and services easily accessible on a self-service basis by developers around the world who are looking to create innovative applications and integrations.

An example of an open API is the Google Maps API that is used across third-party applications (such as ridesharing and food delivery apps) to enable location tracking and mapping.

Internal APIs are the opposite of open APIs in that they are inaccessible to external consumers and only available to an organization’s internal developers. Internal APIs can enable enterprise-wide initiatives from the adoption of DevOps and microservice architectures to legacy modernization and digital transformation. The use and reuse of these APIs can enhance an organization's productivity, efficiency, and agility.

An example of a reusable internal API is if a call center team created a customer information API used in a call center application to access their name, contact information, account info, etc. That team can then reuse this same API in a customer-facing web application or mobile application.

Partner APIs fall somewhere in the middle of internal and external APIs. They are APIs that are accessed by others outside the organization with exclusive permissions. Usually, this special access is afforded to specific third-parties to facilitate a strategic business partnership.

A common use case of a partner API is when two organizations want to share data with each other — such as a county’s health department and a hospital within that county. A partner API would be set up so each organization has access to the necessary data with the right set of credentials and permissions.

Another area of choice for an API is which architectural style or styles will be employed. It’s critical to choose an architectural style or pattern that best supports the intended use of the API if certain functional capabilities are needed. This tends to be an API design decision that is made by more technically-inclined teams.

Before making this decision, you’ll need to have a basic understanding of what infrastructure is already in place — whether the systems are on-premise or cloud-based, which systems and datasets need to be used, what security protocols need to be implemented, and what functionalities are needed. In the spirit of API-first design, the desired functionality and user experiences should inform changes to the legacy IT estate rather than allowing the status quo of the legacy IT estate to dictate functionality or experience.

There are various styles of architecture for APIs, as well as varying data formats within these styles, below we’ve listed some of the most common:

• REST: REST (Representational State Transfer) is an architectural style that separates the concerns of the API consumer from the API provider by relying on commands that are built-into the underlying networking protocol. Clients use the included links and forms to perform actions (e.g. read, update, share, approve. etc.). HTML is the best known example of this style and there are several other formats just for APIs (HAL, CollectionJSON, Siren, etc.). There are many benefits of REST APIs — including flexibility, and ability to accommodate popular data formats like JSON and XML among others.
• RPC: Remote Procedure Calls — or RPCs — typically require developers to execute specific blocks of code on another system. RPC-style remote invocation of procedures other systems usually requires developers to call those procedures by name. RPC is protocol-agnostic, which means it has the potential to be supported on many protocols, but also loses the benefits of using native protocol capabilities (e.g. caching). The proliferation of non-standard procedure names from one RPC API to the next results in tighter coupling between API consumers and providers which in turn overburdens developers involved in all aspects of an RPC-driven API ecosystem. RPC architectural patterns can be observed in popular API technologies such as SOAP, GraphQL, and gRPC.
• Event-driven/Streaming: Sometimes referred to as evented, real-time, streaming, asynchronous, or push architectures, event-driven APIs don’t wait for an API consumer to call them before delivering a response. Instead, a response is triggered by the occurrence of an event. These services expose events to which clients can subscribe to receive updates when values on the service change. There are a handful of variations for this style including (among others) reactive, publish-and-subscribe, event notification, and CQRS.

We are surrounded by all kinds of events to which this API pattern is well-suited. Here are just a few:

• A Twitter account issues a new tweet.
• The temperature on a remote thermometer changes.
• A vehicle passes over a sensor in the pavement.
• A security camera detects motion in its field of view.
• An electro-cardiography machine detects an irregular heartbeat.
• An emergency exit door is opened.
• A smoke detector detects smoke.

Designing and managing effective APIs requires many considerations. The above content should provide a snapshot of the different decisions organizations need to make when preparing to design, deploy, and manage an API. For more information, download our whitepaper on API-led connectivity.