As APIs proliferate, managing the constantly growing and evolving API landscapes inside and across organizations becomes a challenge. Part of the management challenge is for APIs to be able to describe themselves, so that users and tooling can use descriptions for finding and filtering APIs. A standardized labeling scheme can help to cover some of the cases where API self-description allows API landscapes to become more usable and scalable. In this paper we present the vision for standardized API labels, which summarize and represent critical aspects of APIs. These aspect allow consumers to more easily become aware of the kind of dependency they are going to establish with the service provider when choosing to use them. API labels not only summarize critical coupling factors, but also can include claims that require to be validated by trusted third parties.
I will eat this foodI will throw away this foodIt depends
Platform for Privacy Preferences Project (W3C 2002)
What about APIs?
API Discovery: How to trust provider claims?
API Management: Which API do we depend on?
As a consumer, which Type of API Label would you look for?
Human-readable (visual) format to summarize API descriptions
Include hyperlinks to original specifications
Machine processable for automated API landscape management
What about WSDL, WADL, OpenAPI?
API Labels are not meant to completely specify APIs and replace existing languages and service discovery tools
Instead, they include complementary information currently not found in API descriptions as written by service providers, because this information may include claims that need to be verified by trusted third parties.
Recipe for API Labels
Discoverability: Findable Labels
Flexibility: Extensible Label Types
(See the paper for details)
May Contain Nuts: The Case for API Labels
API Management: Is manual registration enough?
API Discovery: How to trust descriptions?
API Labels: Self-Describing, Standard and Certified API Classification
Are people really using Programmable Web to discover APIs?
What's the business model for the API label certification authority?
How do you define an extensible but standard set of label types and values?
How to use Schema.org as meta-data representation for API Labels?
What's the label lifecycle?
How often are labels checked? do they need an expiration? Can caching play a role? How to revoke labels?
What's the relationship between the home document of the API and the labels?