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 [5]
  3. API Product Landscapes [5]
  4. Continuous Architecting [4]
  5. Existing Labeling Schemes [8]
  6. Making API Labels Work [4]
  7. Conclusions [3]
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 [5]
  3. API Product Landscapes [5]
  4. Continuous Architecting [4]
  5. Existing Labeling Schemes [8]
  6. Making API Labels Work [4]
  7. Conclusions [3]
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



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

(13) API Marketplaces

api-marketplaces.png

API Product Landscapes

Outline (API Product Landscapes)

  1. Introduction [4]
  2. Motivation [5]
  3. API Product Landscapes [5]
  4. Continuous Architecting [4]
  5. Existing Labeling Schemes [8]
  6. Making API Labels Work [4]
  7. Conclusions [3]
API Product Landscapes Erik Wilde : May Contain Nuts: The Case for API Labeling

(15) Digital Transformation is Digital Deconstruction

United StatesAustraliaJapanSouth AfricaColombiaPoland

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

(16) Internal and External API Usage

Internal and External API Usage

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

(17) 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


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

(18) 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 succeeding in fast-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 part of development → 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

(19) API Scale Matters

Digital Transformation and API Landscapes: Focus and Scale

Continuous Architecting

Outline (Continuous Architecting)

  1. Introduction [4]
  2. Motivation [5]
  3. API Product Landscapes [5]
  4. Continuous Architecting [4]
  5. Existing Labeling Schemes [8]
  6. Making API Labels Work [4]
  7. Conclusions [3]
Continuous Architecting Erik Wilde : May Contain Nuts: The Case for API Labeling

(21) Continuous Architecting: Continuity and Scale

Continuous Architecting: Continuity and Scale

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

(22) Observability



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

(23) API Lifecycle and Labels

label-lifecycle.png

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

(24) Data Driven API Management



Making API Labels Work

Outline (Making API Labels Work)

  1. Introduction [4]
  2. Motivation [5]
  3. API Product Landscapes [5]
  4. Continuous Architecting [4]
  5. Existing Labeling Schemes [8]
  6. Making API Labels Work [4]
  7. Conclusions [3]
Making API Labels Work Erik Wilde : May Contain Nuts: The Case for API Labeling

(35) Labels as First-Class Concepts



Making API Labels Work Erik Wilde : May Contain Nuts: The Case for API Labeling

(36) API Label Types



Making API Labels Work Erik Wilde : May Contain Nuts: The Case for API Labeling

(37) Label Design Spectrum

{ "labels": {
    "API": {
      "version": "1.3.42",
      "SPDX-license": "ADSL",
      "http://example.com/APIlabels/demotype": "some label value"
}}}


Making API Labels Work Erik Wilde : May Contain Nuts: The Case for API Labeling

(38) Guidelines for API Labels



Conclusions

Outline (Conclusions)

  1. Introduction [4]
  2. Motivation [5]
  3. API Product Landscapes [5]
  4. Continuous Architecting [4]
  5. Existing Labeling Schemes [8]
  6. Making API Labels Work [4]
  7. Conclusions [3]
Conclusions Erik Wilde : May Contain Nuts: The Case for API Labeling

(40) API Label Takeaways



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

(41) Labels for Long-Term Landscaping

prometheus-engineer.jpg

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

(42) 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]