Engineering the Future of Software
29–31 Oct 2018: Tutorials & Conference
31 Oct–1 Nov 2018: Training
London, UK

May Contain Nuts: The Case for API Labeling

Erik Wilde (API Academy)
15:5016:40 Monday, 29 October 2018
Distributed systems
Location: King's Suite - Balmoral Level: Beginner
Secondary topics:  Best Practice, Overview

Who is this presentation for?

Architects, API users, API developers, Integration specialists

Prerequisite knowledge

This session is intended for API developers, API users, and managers of API ecosystems. It provides an overview of how APIs can be described, documented, and labeled in today's quickly evolving API landscapes. Attendees should have a basic understanding of what APIs are, how they are being used, and how they are the underpinning of many of today's digital transformation approaches.

What you'll learn

As the idea of "API products" is becoming more mainstream, it becomes increasingly important to think about typical product features. One of these features is a labeling system that allows certain aspects of APIs to be described. Using this description, users and managers can get a better understanding of (some of) the important aspects of an API. This idea works very similar to product labels from other areas of commodity products, such as food. Labeling systems are used to provide a focused and unified view of some of a product's important aspects.


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/OpenAPI. The non-functional 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, for example for food or for machinery. There often is 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 how APIs can be described and/or documented. However, there still is some uncertainty how to best combine these, and how to use them so that API description, documentation, and labeling can be combined. This presentation provides an overview of the existing approaches, how to use them, and proposes an additional layer on top of which API labeling becomes more unified, and thus more useful.

Photo of Erik Wilde

Erik Wilde

API Academy

An expert in protocol design and structured data, Erik Wilde consults with organizations to help them get the most out of APIs and microservices. Erik has been involved in the development of innovative technologies since the advent of the Web and is active in the IETF and W3C communities. He obtained his PhD from ETH Zurich and served as Associate Adjunct Professor at Berkeley before working at EMC, Siemens and now CA Technologies.

Leave a Comment or Question

Help us make this conference the best it can be for you. Have questions you'd like this speaker to address? Suggestions for issues that deserve extra attention? Feedback that you'd like to share with the speaker and other attendees?

Join the conversation here (requires login)