APIs are the only visible parts of services in API-based service landscapes. The technical aspect of APIs has been widely discussed with description languages such as Swagger and OpenAPI. The nonfunctional aspects are harder to formalize but can also benefit from a framework in which information can be represented and used.
The idea of API labels is equivalent to that of standardized labeling systems in other product spaces, such as for food or machinery, which often have a framework in place that allows users to understand a few key (and often safety-critical) aspects of the product. This framework is not intended to be a complete and exhaustive description of the product. Instead, it focuses on areas that are important and helpful to make an initial product selection.
In the API space, numerous standards and best practices have evolved to describe and document APIs, but there’s still uncertainty how to best use them to combine API description, documentation, and labeling. Erik Wilde offers an overview of the existing approaches, demonstrates how to use them, and proposes an additional layer on top of which API labeling becomes more unified, and thus more useful.
Erik Wilde is a principal consultant at the API Academy, where he helps organizations get the most out of APIs and microservices. An expert in protocol design and structured data, Erik has been involved in the development of innovative technologies since the advent of the web. Previously, he was an associate adjunct professor at UC Berkeley and worked at EMC and Siemens. Erik is active in the IETF and W3C communities. He holds a PhD from ETH Zurich.
©2018, O’Reilly UK Ltd • (800) 889-8969 or (707) 827-7019 • Monday-Friday 7:30am-5pm PT • All trademarks and registered trademarks appearing on oreilly.com are the property of their respective owners. • firstname.lastname@example.org