A bookstore might let independent developers search its catalog, give a delivery company access to assigned shipments, and let its own services update inventory. These interactions serve different audiences, even when they rely on some of the same underlying data.

Labels such as public, private, partner, and internal describe who should use an API. They influence documentation, access decisions, support, and how changes reach consumers.

This chapter explains the labels, their overlap, and how to apply them without confusing the intended audience with who can reach an endpoint.

A provider offers a public API to a broad audience of external developers and a partner API to selected external organizations through an approved relationship. A provider reserves a private API for its own use instead of offering it for general external integration. An internal API usually connects services, tools, or teams within that organization.

Organizations often use private and internal interchangeably. For example, AWS's introductory API documentation describes private APIs as interfaces that teams use within an enterprise. There is no need to force every API into four separate, exclusive categories.

For the examples here, private describes APIs the bookstore reserves for its own applications and systems. Internal identifies the subset its services and staff tools use. This is a working distinction for discussing the examples, not a universal naming rule. Other organizations may use private more broadly for any restricted API, including partner interfaces.

These labels describe the supported audience. They do not specify a protocol, data format, or authentication mechanism. An API's audience also does not determine whether every operation exposes the same information.

Suppose the bookstore publishes a catalog API so reading apps can find titles and link readers to its store. Developers can discover the documentation and apply the published access process without negotiating a separate delivery or distribution partnership.

That makes it a public API. It does not imply that every request is anonymous, that usage is free, or that all bookstore data is public. A public offering can require registration, credentials, payment, or approval under a broadly available program. AWS likewise notes that public APIs can have access requirements and costs.

The bookstore could allow anonymous retrieval of basic book details while requiring an account for larger catalog searches. If it also offers operations on a reader's saved lists, those operations still need permission to access that reader's information. A publicly offered interface can carry private user data under controlled access.

The broad audience changes how the provider communicates. Developers need documentation they can use without access to the bookstore's internal chat or source code. Setup instructions, examples, error explanations, and a way to obtain support become part of making the API usable.

The provider also has limited control over consumer updates. A reading app may release monthly, while another integration may remain unchanged for a year. A public API therefore needs clear expectations about supported behavior and how the provider will announce changes.

Public APIs do not automatically require large-scale infrastructure. A small catalog API may serve modest traffic. The defining feature is who the provider invites to build against it, not how many requests it currently receives.

A partner is an external organization the provider approves for a particular integration. In the bookstore example, a delivery company needs shipment information so it can collect parcels and report delivery progress.

The partner API can expose the operations that relationship requires: retrieve assigned shipments and submit delivery updates. It need not expose customer purchase histories, supplier costs, or shipments that belong to another carrier.

This creates a different access process from the public catalog API. Onboarding, the process of setting up an integration, may include agreeing on supported operations, issuing access credentials, testing with sample shipments, and establishing operational contacts. These are possible arrangements for this example, not mandatory features of every partner API.

Recognizing the partner is only one part of the access decision. Authentication establishes who is making a request. Authorization determines whether that caller may perform the requested action on the requested information.

For example, Carrier A being an approved partner does not authorize it to read Carrier B's shipments. The following simplified flow shows the checks for retrieving a shipment:

The relationship gives the provider a basis for granting specific access. It does not make the partner trusted for every operation. The service must enforce the permissions the provider grants through that relationship on each relevant request.

Partner integrations also outlive individual requests. The provider needs a way to change or withdraw access when a carrier's responsibilities change or the relationship ends. A small, known audience can make communication easier, but the partner still owns its software and release schedule.

The bookstore's website and mobile app need basket operations that fit the shopping experience. The provider may reserve those operations for its own products without offering them as a supported interface for independent developers.

Using this chapter’s definitions, that is a private API. Customers can use the application, but the provider has not invited them to build separate integrations against its app backend.

The distinction concerns the intended software consumer, not whether the person using the app is an employee. A customer-facing mobile app can call an API the company reserves for its own software.

Such an API may still be reachable over the internet. Its requests may be visible to someone inspecting their own browser traffic. An unpublished URL or an assumption that requests come from the official app does not enforce access rules. The server must verify the user's permission to read or modify a particular basket, regardless of how the client constructed the request.

Ownership can simplify coordination. The bookstore controls the website and its backend, so it can plan their changes together. Mobile clients require more care because installed versions remain on customer devices after a new release becomes available.

Private therefore does not mean disposable or safe to change without checking consumers. It means the provider has chosen a narrower supported audience, with update constraints that depend on those consumers.

An internal inventory API might allow the checkout service to reserve stock and the warehouse tool to record received books. Both consumers belong to the bookstore, but they have different responsibilities.

The checkout service does not need permission to rewrite supplier costs. The warehouse tool does not need permission to refund customers. Being inside the organization is insufficient reason to grant either consumer every operation.

NIST's zero trust guidance states that network location or organizational ownership alone should not establish trust. Applied here, an internal service still needs appropriate identity and access checks for the resources it uses.

Internal APIs also need identifiable owners, documented behavior, and a way to communicate changes. A checkout team cannot reliably use an inventory operation if nobody can explain when a reservation expires or how the service reports failures.

The amount of coordination depends on the consumers. Two components that one team releases together may be straightforward to update. An inventory service that checkout, warehouses, reporting, and customer support all use has a wider dependency network, even if every team belongs to the same company.

The bookstore can expose several audience-specific interfaces while sharing service logic behind them:

These are logical interfaces for different consumers. The diagram does not require four separate servers. Deployment can vary while the supported operations and permissions remain explicit.

Three questions help remove ambiguity from a discussion about API access:

A partner shipment API could accept connections over the internet and still reject every request without valid partner access. A private app API could also be internet-reachable. An internal inventory API might be reachable only through the organization's network, while restricting operations separately by service identity.

Some products use private API as a specific networking term. In Amazon API Gateway, clients access a private REST API through a VPC endpoint rather than a public internet endpoint. A VPC, or Virtual Private Cloud, is an isolated virtual network. That product-specific meaning describes how clients connect. Here, we classify APIs by who uses them.

This diagram shows why reaching an endpoint is only one step toward using a protected operation:

Network restrictions can reduce exposure, but they do not express every business permission. Similarly, publishing documentation describes a supported interface; it does not grant a caller access to every record behind it.

The bookstore's access behavior can make these distinctions concrete:

These outcomes define the example's access policy. The labels alone would not be enough to determine them.

For each interface, record the supported consumers, the operations they need, the data they may receive, and the team responsible for maintaining the contract. Also record how consumers obtain access and how the provider will communicate changes.

An interface can serve multiple audiences if its contract and permissions support them. For example, the bookstore's own website can use the public catalog API. Calling it from company-owned software does not make that public offering internal.

Conversely, giving a carrier temporary access to an inventory endpoint does not automatically make that endpoint ready to support partners. Its response may include warehouse details the carrier does not need, or its behavior may assume close coordination between internal teams. Expanding the audience requires reviewing those assumptions and defining what external consumers can expect.

Separate interfaces can help when audiences need substantially different operations or guarantees. Shared interfaces can avoid duplication when their needs align. The choice should follow consumer requirements and access boundaries, rather than creating a separate deployment for every label.

Public APIs support a broad external audience, while partner APIs support selected external relationships. Private and internal often overlap; they generally describe interfaces the provider reserves for its own products, teams, and services.

State what these labels mean in your organization. Treat the supported audience, network reachability, and permissions as separate decisions, and define the actual operations and data each consumer may access.