May Contain Nuts: The Case for API Labeling

O'Reilly [https://conferences.oreilly.com/] Software Architecture Conference [https://conferences.oreilly.com/software-architecture/], London, UK [https://conferences.oreilly.com/software-architecture/sa-eu]

Erik Wilde
API Academy, CA Technologies

October 29, 2018

Creative Commons License [http://creativecommons.org/licenses/by/3.0/]

This work is licensed under a CC
Attribution 3.0 Unported License
[http://creativecommons.org/licenses/by/3.0/]

Contents Erik Wilde : May Contain Nuts: The Case for API Labeling

Contents

Erik Wilde : May Contain Nuts: The Case for API Labeling

(2) Summary

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.



Introduction

Outline (Introduction)

  1. Introduction [4]
  2. Motivation [4]
  3. API Product Landscapes [5]
  4. Continuous Architecting [3]
  5. Existing Labeling Schemes [3]
  6. Labels in Real Life [5]
  7. Using API Labels [4]
    1. Labels as First-Class Citizens [2]
    2. API Label Strawman [2]
  8. Conclusions [1]
Introduction Erik Wilde : May Contain Nuts: The Case for API Labeling

(4) @dret on Twitter/GitHub

dret

Introduction Erik Wilde : May Contain Nuts: The Case for API Labeling

(5) API Academy [http://www.apiacademy.co/]

API Academy

Introduction Erik Wilde : May Contain Nuts: The Case for API Labeling

(6) Continuous API Management

Continuous API Management: Making the Right Decisions in an Evolving Landscape

Introduction Erik Wilde : May Contain Nuts: The Case for API Labeling

(7) About Me



Motivation

Outline (Motivation)

  1. Introduction [4]
  2. Motivation [4]
  3. API Product Landscapes [5]
  4. Continuous Architecting [3]
  5. Existing Labeling Schemes [3]
  6. Labels in Real Life [5]
  7. Using API Labels [4]
    1. Labels as First-Class Citizens [2]
    2. API Label Strawman [2]
  8. Conclusions [1]
Motivation Erik Wilde : May Contain Nuts: The Case for API Labeling

(9) Useful Information in Diverse Landscapes

Food Labels

Motivation Erik Wilde : May Contain Nuts: The Case for API Labeling

(10) Label Properties and Problems

Food Quality Labels in Switzerland

Motivation Erik Wilde : May Contain Nuts: The Case for API Labeling

(11) Labels are Languages

water-food-label.jpg

Motivation Erik Wilde : May Contain Nuts: The Case for API Labeling

(12) Labels are Constraints



API Product Landscapes

Outline (API Product Landscapes)

  1. Introduction [4]
  2. Motivation [4]
  3. API Product Landscapes [5]
  4. Continuous Architecting [3]
  5. Existing Labeling Schemes [3]
  6. Labels in Real Life [5]
  7. Using API Labels [4]
    1. Labels as First-Class Citizens [2]
    2. API Label Strawman [2]
  8. Conclusions [1]
API Product Landscapes Erik Wilde : May Contain Nuts: The Case for API Labeling

(14) Digital Transformation is Digital Deconstruction

United StatesAustraliaJapanSouth AfricaColombiaPoland

API Product Landscapes Erik Wilde : May Contain Nuts: The Case for API Labeling

(15) Transformation 1-2-3

  1. Vision (Why) explains the ultimate goal
    • Be more active when it comes to exploring new opportunities
    • Be more reactive when it comes to adapting to new challenges
  2. Strategy (What) maps out resource allocation
    • Business strategy focuses on success in faster-changing environments
    • Organization strategy focuses on making the organization being more change-ready
    • Technical strategy focuses on how to enable and support constant transformation
  3. Execution (How) details what to do along the way
    • Loose coupling for minimizing IT-inflicted dependencies → Microservices
    • Agility for embracing feedback as necessary development input → DevOps
    • Landscapes as a way to move from integration to interaction → APIs


API Product Landscapes Erik Wilde : May Contain Nuts: The Case for API Labeling

(16) API Scale Matters

Digital Transformation and API Landscapes: Focus and Scale

API Product Landscapes Erik Wilde : May Contain Nuts: The Case for API Labeling

(17) Internal and External API Usage

Internal and External API Usage

API Product Landscapes Erik Wilde : May Contain Nuts: The Case for API Labeling

(18) API Usage Scenarios

  1. Private APIs for internal usage
    • Trust is a smaller issue (no intentionally malicious usage)
    • Risk needs to be managed for operational stability
  2. Partner/Public APIs provided to external consumers
    • Trust can be used as differentiating factor
    • Risk management means keeping SLAs and other claims
  3. Partner/Public APIs consumed from external providers
    • Trust depends on the relationship with the provider
    • Risk should be managed as external dependency


Continuous Architecting

Outline (Continuous Architecting)

  1. Introduction [4]
  2. Motivation [4]
  3. API Product Landscapes [5]
  4. Continuous Architecting [3]
  5. Existing Labeling Schemes [3]
  6. Labels in Real Life [5]
  7. Using API Labels [4]
    1. Labels as First-Class Citizens [2]
    2. API Label Strawman [2]
  8. Conclusions [1]
Continuous Architecting Erik Wilde : May Contain Nuts: The Case for API Labeling

(20) Continuous Architecting: Continuity and Scale

Continuous Architecting: Continuity and Scale

Continuous Architecting Erik Wilde : May Contain Nuts: The Case for API Labeling

(21) Observability



Continuous Architecting Erik Wilde : May Contain Nuts: The Case for API Labeling

(22) Data Driven API Management



Labels in Real Life

Outline (Labels in Real Life)

  1. Introduction [4]
  2. Motivation [4]
  3. API Product Landscapes [5]
  4. Continuous Architecting [3]
  5. Existing Labeling Schemes [3]
  6. Labels in Real Life [5]
  7. Using API Labels [4]
    1. Labels as First-Class Citizens [2]
    2. API Label Strawman [2]
  8. Conclusions [1]
Labels in Real Life Erik Wilde : May Contain Nuts: The Case for API Labeling

(28) Food Labels

Food Labels

Labels in Real Life Erik Wilde : May Contain Nuts: The Case for API Labeling

(29) Safety Labels

Product Safety Labels

Labels in Real Life Erik Wilde : May Contain Nuts: The Case for API Labeling

(30) Label Design and Complexity

vacuum-label.png

Labels in Real Life Erik Wilde : May Contain Nuts: The Case for API Labeling

(31) OCD? Landscape Management!

vacuum-landscape.png

Labels in Real Life Erik Wilde : May Contain Nuts: The Case for API Labeling

(32) Why Do Labels Work?

Goal: Information about all/many products in large and diverse landscapes.

Non-goal: Every possible detail about every single product.



Using API Labels

Outline (Using API Labels)

  1. Introduction [4]
  2. Motivation [4]
  3. API Product Landscapes [5]
  4. Continuous Architecting [3]
  5. Existing Labeling Schemes [3]
  6. Labels in Real Life [5]
  7. Using API Labels [4]
    1. Labels as First-Class Citizens [2]
    2. API Label Strawman [2]
  8. Conclusions [1]

Labels as First-Class Citizens

Outline (Labels as First-Class Citizens)

  1. Introduction [4]
  2. Motivation [4]
  3. API Product Landscapes [5]
  4. Continuous Architecting [3]
  5. Existing Labeling Schemes [3]
  6. Labels in Real Life [5]
  7. Using API Labels [4]
    1. Labels as First-Class Citizens [2]
    2. API Label Strawman [2]
  8. Conclusions [1]
Labels as First-Class Citizens Erik Wilde : May Contain Nuts: The Case for API Labeling

(35) Standalone API Labels



Labels as First-Class Citizens Erik Wilde : May Contain Nuts: The Case for API Labeling

(36) Embedded API Labels



API Label Strawman

API Label Strawman Erik Wilde : May Contain Nuts: The Case for API Labeling

(38) API Label Format



API Label Strawman Erik Wilde : May Contain Nuts: The Case for API Labeling

(39) API Label Types

  • Requirements for API label types
    • Well-known and continuously evolving set of existing label types
    • Easy discovery of current set of well-known label types
    • Robust coexistence of well-known and proprietary label types


Conclusions

Outline (Conclusions)

  1. Introduction [4]
  2. Motivation [4]
  3. API Product Landscapes [5]
  4. Continuous Architecting [3]
  5. Existing Labeling Schemes [3]
  6. Labels in Real Life [5]
  7. Using API Labels [4]
    1. Labels as First-Class Citizens [2]
    2. API Label Strawman [2]
  8. Conclusions [1]
Conclusions Erik Wilde : May Contain Nuts: The Case for API Labeling

(41) Thanks! Q&A

What's Next?

October 29, 2018 O'Reilly [https://conferences.oreilly.com/] Software Architecture Conference [https://conferences.oreilly.com/software-architecture/], London, UK [https://conferences.oreilly.com/software-architecture/sa-eu]