Designing Private, Partner, and Public APIs: What’s the Difference?

One of the defining characteristics of an API is that it should be reusable, but that doesn’t say much about the scope of an API, i.e. who the intended consumers are. A popular distinction to make is between private, partner, and public APIs.

• A private API is consumed within an organization and not intended to be exposed to consumers outside of the organization.
• A partner API is consumed by partners of your organization, meaning that there is an established relationship and some framework (often some form of contractual agreement).
• A public API is intended to be consumed by anybody interested in the API and does not depend on or establish a close relationship; the goal is to make consumption easy, and to attract as many consumers as possible.

See also: 4 types of APIs and what makes each one unique

Does this distinction translate into differences in API design? It very well might: after all, the most important success criterion of an API is that is drives value. If it takes a specific design to better do that, then it makes sense to design an API differently based on the private/partner/public distinction.

There are four possible distinctions between private/partner/public APIs that may be used as design constraints for specific design decisions:

• Domain Knowledge: How extensive is the domain familiarity that you can build on when designing the API for the intended consumers?
• Relationship with Consumers: What is your relationship with consumers, and how does that translate into API design decisions?
• Security/Threat Model: How are identity and authorization established, and what it is the threat model that you are using for your API consumers?
• API Landscape Context: What is the API landscape that you are designing for, and where some design coherence would be beneficial?

Always keep in mind that treating APIs as products is a good idea, and that designing these products for their intended consumers will help you to make better design decisions. Learn more about these constraints and how they can be used to improve API design.