May contain nuts: The case for API labeling

Description

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.