The management approach for internal vs. external APIs

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 build unique integrations between each application, or manually build connections between back-end systems.

What is an external API?

External APIs expose a business's internal resources to outside users or applications. For instance, third-party developers who need to access data or services that belong to a business, or who want to build apps that integrate with the business's platform, can do so using external APIs.

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

Internal vs. external API management

In terms of technical design and core functionality, internal and external APIs work in basically the same way. Developers can use API design styles such as REST, SOAP or GraphQL to build either type of API, and the process of 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. Six major areas where the management specifics differ for internal vs. external APIs are:

• publishing and discovery;
• security and access control;
• policy enforcement;
• performance testing;
• monitoring and metrics tracking; and
• deprecation/sunsetting processes.

Publishing and discovery

API publishing and discovery help developers find APIs so they can integrate them into their applications. APIs should be discoverable whether they are 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 makes them easy for any developer to find and understand quickly -- even those who know very little about the organization's unique technical ecosystem. For internal APIs, however, you'll need to know more about what the target developers already know, and the specific capabilities or functionalities they'll need.

Developers who rely on internal APIs are generally more proactive about searching for and finding those APIs on their own. With external APIs, however, the organization is often competing with other businesses to grab developers' attention and get them to use the APIs. As such, the development team will need to think somewhat like a marketer when it comes to the API publishing and discovery process.

Security and access control

The fact that internal APIs reside within internal systems doesn't eliminate the need to secure them. It does, however, simplify API security, because internal APIs are less exposed to threats that exist outside your organization. If you have a finite amount of resources for API security, invest the bulk of them in securing external APIs.

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

Most API management tooling providers that feature enterprise-grade capabilities, such as Nginx and RapidAPI, include provisions for both internal and external API security in one package. However, the development team still needs to ensure those APIs are identified and secured appropriately.

Policy enforcement

API policies play a crucial role in controlling how both internal and third-party developers can work with that API, and what they can do with it. For example, a policy may limit the number of requests that an application can make to an API within a fixed 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 likely to be misused or abused. But even internal APIs will need some guiding policies that ensure all internal developers and systems have equal access to API resources, and to prevent noisy neighbor issues when multiple applications or developers request to use the same internal API.

Performance testing

It's important to test internal and external APIs, but each requires unique types of tests. This is because use cases or request patterns for external APIs are likely broader in scope than they are for most internal APIs.

With internal APIs, developers can conduct performance tests based on the specific API use cases the organization must support, because those are likely well-documented. By contrast, it's difficult to predict what third-party developers might try to do with an external API, necessitating broader test coverage. One strategy is to create mock APIs that simulate as many potential use cases as possible. The ability to do this reliably, however, depends on how accurately developers can mock the API and predict user behavior.

Monitoring and metrics tracking

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 a few ways developers can calibrate monitoring toward one or the other. With internal APIs, developers can typically collect as much data as desired about API performance, because they can readily observe both the API server and client components. With external APIs, developers may be limited to metrics available from the server, unless they have direct access to the clients or can accurately mock the request-response procedures.

Deprecation and sunsetting

When an API reaches the extent of its usability, it's often easier to deprecate and sunset internal APIs than external APIs. With internal APIs, it's typically possible to notify all stakeholders in as little as a few weeks ahead of the change. If those stakeholders are unhappy about the end of the API's availability, it will be easier to explain the reasons for sunsetting the API and, if necessary, provide a usable substitute.

With external APIs, developers must handle deprecation and sunsetting carefully. To avoid garnering a bad reputation within the developer community, organizations should announce any API deprecations well in advance, meaning months or maybe even years before the API disappears. There is also much more legwork involved to help developers transition to an alternate API, if there is one. If there isn't an alternate, the organization should at least offer some advice on next steps for developers who rely on that API.