Pattern Sections
Pattern: Public API
a.k.a. Open API (a truly open API is a Public API without an API Key or other authentication means)
Context
It has been decided to provide a system with a remote API that exposes one or more API endpoints. The API clients that are supposed to use the API (and therefore must reach it) reside in different organizations, possibly even in different countries. They might or might not be known to the provider.1
Problem
How can an API be made available to an unlimited and/or unknown number of API clients outside the organization that are globally, nationally, and/or regionally distributed?
Forces
API visibility is determined by the hosting location and its network connections (e.g., the Internet, an extranet, or a company-internal network or even a single data center). Decision criteria include:
- Business model
- Target audience size, location, and diversity
- Complexity and maturity of required backend systems and data stores
- Security considerations
- Budgets (development and operations, maintenance and evolution)
Pattern forces are explained in depth in the book.
Solution
Expose the API on the public Internet along with a detailed API Description that describes both functional and nonfunctional properties of the API.
Sketch
A solution sketch for this pattern from pre-book times is:
Example
In the fictitious insurance case study Lakeside Mutual, the interface between the customer self-service application frontend, implemented as JavaScript running in the browser, and the corresponding backend is an example of a Public API.
Are you missing implementation hints? Our papers publications provide them (for selected patterns).
Consequences
The resolution of pattern forces and other consequences are discussed in our book.
Known Uses
All APIs listed on the Programmable Web API directory implement this pattern; so there are 100s if not 1000s known uses as of today (and counting):
- Google Calendar API, Google Maps, Google Knowledge Graph Search API
- Facebook Graph API
- Atlassian JIRA Cloud REST API and JIRA Server Platform REST API
- GitHub API
- YouTube Data API (v3)
- Twitter API
- LinkedIn REST API
- Instagram API
- Amazon Web Services family products/services all exposing Web APIs and/or offering SDKs (e.g. S3, EC2)
- Stripe API for Web payments
- PayPal
- Open Weather Map
- Quandl
- Cloud Convert
- Microsoft Graph API which is OData-based
- Heroku Platform API
- Flickr API and App Garden
- eBay
More Information
Related Patterns
A Public API either supports Frontend Integration or Backend Integration scenarios and stories. The siblings of this pattern that describe other visibility levels are Community API and Solution-Internal API.
The Public Cloud pattern in Fehling et al. (2014) has a similar context and intent, but is more concerned about IT infrastructure (rather than API design).
The pattern can be combined with the Backends For Frontends architecture described by S. Newman.
Other Sources
Many known uses can be found in the API Directory at Programmable Web and in the Directory of API definitions by APIs.guru.
References
Note that this context is similar to that of the sibling patterns Community API and Solution-Internal API.↩︎