The approach to managing internal APIs versus external APIs

Both internal and external APIs perform the same basic function, in terms of providing the data and integrations needed to facilitate application operations. However, depending on whether or not they manage internal APIs, architects and developers will need to adjust how they monitor and manage these APIs. Otherwise, it could have drastic effects on the usability of these APIs and possibly lead to catastrophic data exposure.

In this article, we’ll quickly review what defines an internal API versus an external API. Next, we’ll go over six specific areas of API management where each type requires a slightly different approach.

What is an internal API?

Internal APIs provide access to sensitive resources within an organization’s software system. They simplify the process of linking back-end systems or data between the multitude of applications that control internal operations.

Any application can use a standardized internal API to integrate with an internal system. This eliminates the need to create unique integrations between each application or manually create connections between back-end systems.

What is an external API?

External APIs expose a company’s internal resources to external users or applications. For example, third-party developers who need access to company-owned data or services, or want to build apps that integrate with the company’s platform, can do so at using external APIs.

Despite the name, some teams may use some external APIs to also manage some integrations between internal apps and back-end systems. But, unlike internal APIs, external APIs are not limited to use within the organization and must be carefully designed, secured, and monitored to protect any sensitive business data they could potentially expose.

Internal vs external API management

In terms of technical design and basic functionality, internal and external APIs essentially work the same way. Developers can use API design styles such as REST, SOAP, or GraphQL to create either type of API, and the process for requesting and sharing data will be similar for each.

When it comes to API management, however, application development and management teams will need to treat internal and external APIs differently. The six main areas where management specifics differ for internal and external APIs are:

  • publishing and discovery;
  • security and access control;
  • policy enforcement;
  • Performance Test;
  • monitoring and tracking metrics; and
  • process of obsolescence/extinction.

Publication and discovery

Publishing and discovering APIs helps developers find APIs so they can integrate them into their applications. APIs must be discoverable, whether internal or external, but the actual publishing process that makes an API discoverable may vary.

When dealing with external APIs, publish in a way that they are easy to find and quickly understand for any developer, even those with very little knowledge of the organization’s unique technical ecosystem. For internal APIs, however, you’ll need to learn more about what the target developers already know and what specific capabilities or features they’ll need.

Developers who rely on internal APIs are generally more proactive in finding and researching these APIs on their own. With external APIs, however, the organization often competes with other companies to get developers’ attention and get them to use the APIs. As such, the development team will need to think a bit like a marketer when it comes to the API release and discovery process.

Security and access control

The fact that internal APIs reside in internal systems does not eliminate the need to secure them. However, it simplifies API security because internal APIs are less exposed to threats that exist outside of your organization. If you have a limited amount of API security resources, invest most of them in securing external APIs.

Access controls for external APIs are often not very granular. An organization typically wants all internal and external developers to be able to use these external APIs, reducing the need to fine-tune who can do what with them. However, internal APIs may require more complex access controls to ensure that only valid stakeholders within your organization can use the APIs.

Most API management tool vendors that offer enterprise-grade functionality, such as Nginx and RapidAPI, include provisions for internal and external API security in a single package. However, the development team still needs to ensure that these APIs are identified and secured appropriately.

Policy enforcement

API policies play a crucial role in controlling how and what internal and third-party developers can work with that API. For example, a policy can limit the number of requests an application can make to an API during a specified period. This type of policy management is important from a performance perspective and prevents API abuse by malicious parties.

As with API security, policy enforcement is most critical for external APIs, which are more susceptible to misuse or abuse. But even internal APIs will need guiding rules to ensure that all internal developers and systems have equal access to API resources, and to avoid noisy neighbor issues when multiple apps or developers request to use the same internal API.

Performance Test

Both internal and external APIs are important to test, but each requires unique types of testing. This is because the use cases or request patterns for external APIs are likely to have a broader scope than for most internal APIs.

With internal APIs, developers can perform performance testing against specific API use cases that the organization needs to support, as these are likely well documented. On the downside, it’s hard to predict what third-party developers might try to do with an external API, which requires broader testing coverage. One strategy is to create dummy APIs that simulate as many potential use cases as possible. However, the ability to do this reliably depends on how well developers can mock the API and predict user behavior.

Monitoring and tracking metrics

Unlike the other management aspects listed here, API monitoring and performance tracking does not vary significantly between internal and external APIs. Any API used for production purposes, whether by internal or external users, requires careful monitoring for failures and performance degradations.

That said, there are several ways for developers to calibrate monitoring towards one or the other. With in-house APIs, developers can usually collect as much data as they want about API performance because they can easily observe both the API server and client components. With external APIs, developers may be limited to metrics available on the server, unless they have direct access to clients or can accurately simulate request-response procedures.

Abandonment and temporization

When an API reaches the extent of its usability, it is often easier to deprecate and disable internal APIs than external APIs. With internal APIs, it is usually possible to notify all stakeholders just weeks before the change. If these stakeholders are unhappy with the end of the API’s availability, it will be easier to explain the reasons for the API’s extinction and, if necessary, provide a usable substitute.

With external APIs, developers must carefully manage obsolescence and extinction. To avoid gaining a bad reputation within the developer community, organizations should announce any API deprecation well in advance—that is, months or even years before the API don’t disappear. There’s also a lot more legwork to help developers switch to an alternative API, if there is one. If there is no alternative, the organization should at least offer guidance on next steps to developers relying on this API.

Shirlene J. Manley