(4) @dret on Twitter/GitHub

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

• Global Team working on API Strategy and Design topics
  • Matt McLarty [http://www.apiacademy.co/team_member/matt-mclarty/] (Vancouver): @MattMcLartyBC [http://twitter.com/MattMcLartyBC]
  • Mike Amundsen [http://www.apiacademy.co/team_member/mike-amundsen/] (Cincinnati): @mamund [http://twitter.com/mamund]
  • Mehdi Medjaoui [http://www.apiacademy.co/team_member/mehdi-medjaoui/] (San Francisco): @medjawii [http://twitter.com/medjawii]
  • Ronnie Mitra [http://www.apiacademy.co/team_member/ronnie-mitra/] (London): @mitraman [http://twitter.com/mitraman]
  • Erik Wilde [http://www.apiacademy.co/team_member/erik-wilde/] (Zürich): @dret [http://twitter.com/dret]
• Evangelizing ideas and technologies
  • Speaking (conferences, events)
  • Teaching (workshops, bootcamps)
  • Publishing (blogs, articles, books, podcasts [https://soundcloud.com/user-426834320])
  • Doing (side projects on API-related topics)
  • Standardizing (participating in specification work)

(6) Continuous API Management

• Continuous API Management: Making the Right Decisions in an Evolving Landscape [https://www.amazon.com/Continuous-Api-Management-Decisions-Landscape/dp/1492043559]
• Authored by API Academy [http://www.apiacademy.co/] members Mehdi Medjaoui, Erik Wilde, Ronnie Mitra, and Mike Amundsen
• To be published December 2018

(7) About Me

• Ph.D. in Communications Systems [http://dret.net/netdret/publications#wil97b] from ETH Zürich [http://www.ethz.ch/]
• Working on Web Architecture after writing the first Web Technology book [http://dret.net/netdret/publications#wil98]
• UC Berkeley (2006-2011), working on Service Models for Open Government [http://dret.net/netdret/publications#wil09g]
• EMC (2011-2014), working on transforming software products into service platforms
• Siemens (2014-2015), working on using IoT to build WoT (APIs for Things)
• Joined CA [http://www.ca.com/]'s API Academy [http://www.apiacademy.co/] in 2016 and now all about API Strategy and Design
• Active in the usual places such as Twitter [http://twitter.com/dret], GitHub [http://github.com/dret], my blog [http://dret.typepad.com/dretblog/], LinkedIn [http://www.linkedin.com/in/netdret], and flickr [https://www.flickr.com/photos/dret/]

(9) Useful Information in Diverse Landscapes

(10) Label Properties and Problems

(11) Labels are Languages

• Diverse and dynamic set of products
• Decentralized production and consumption
• Market regulation for consumer safety and information
• Never forget about Goodhart's Law [https://en.wikipedia.org/wiki/Goodhart%27s_law]
  • When a measure becomes a target, it ceases to be a good measure.

(12) Labels are Constraints

• Labels emerge for market observability or management
  • Producers use them for product differentiation
  • Consumers use them for product selection
  • Market regulators balance freedom, safety, and transparency
• Labels provide a framework how to enter and succeed in a market
  • Production is only visible when required for label verification/certification
• Labels tend to emerge when markets become big and opaque
  • Establishing visibility/transparency/accountability/safety/trust

(13) API Marketplaces

(15) Digital Transformation is Digital Deconstruction

(16) Internal and External API Usage

(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

(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

(19) API Scale Matters

(21) Continuous Architecting: Continuity and Scale

(22) Observability

• Continuous Architecting is based on four main principles
  1. Design Products with feedback and changeability in mind
  2. Evolve Products based on feedback and with minimal breakage
  3. Landscape Design supports product continuity and landscape evolvability
  4. Landscape Evolution is based on product and consumer feedback
• Observability is a key principle complementing APIs and Microservices
  • Implementation details are hidden and APIs are the only interface
  • API your APIs: Anything that is interesting should become an API
• Observability is based on and complements Continuous Architecting
  • When new observability needs arise they can be added to the landscape and/or products
  • Observability makes sure that the landscape can be observed and improved

(23) API Lifecycle and Labels

(24) Data Driven API Management

• Diversity and Data-Driven can be challenging to balance
  • Diverse APIs can have different properties and expose them differently
  • Data-Driven approaches need some way to manage diversity
• API Labels provide a shared language for representing API data
  • API Labels are different from API description formats
  • Exposing label information can be integrated into CI/CD and automated
• API Labels can be produced and harvested in a variety of ways
  • Self-declaration allows API product teams to publish labels
  • Tool-based labels are created by tools at the product or landscape level
  • Third-party labels can use information from external providers

(26) Food Labels

(27) Safety Labels

(28) Label Design and Complexity

(29) OCD? Landscape Management!

(30) Why Do Labels Work?

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

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

• Designed for specific scenarios and purposes
• Simple/simplified description of relevant product aspects
• Supported across large and diverse sets of products (possibly across categories)
• Defined/assigned/verified/certified by various players (owners/managers/authority/automated)

(31) OpenAPI

• OpenAPI Info Object [https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#info-object] represents API metadata as part of an API description
  • Small set of predefined fields (title and version are required)
  • Extensions can be added via OpenAPI Specification Extensions [https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#specificationExtensions]

info:
  title: Sample Pet Store App
  description: This is a sample server for a pet store.
  termsOfService: http://example.com/terms/
  contact:
    name: API Support
    url: http://www.example.com/support
    email: support@example.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.1

(32) APIs.json

• APIs.json [http://apisjson.org/] focuses on a high-level API landscape view
  • Small set of required fields (for APIs and the whole organization)
  • Extensions probably allowed except for reserved words

{
    "name": "Fitbit",
    "description": "Fitbit designs products that track everyday health and fitness, empowering and inspiring people to lead healthier, more active lives.",
    "image": "https://www.fitbit.com/images/common/logo_with_trademark.png",
    "tags": [
        "fitness"
    ],
    "created": "2015-01-01",
    "modified": "2015-01-01",
    "url": "https://www.fitbit.com/apis.json",
    "specificationVersion": "0.14",
    "apis": [
        {
            "name": "Fitbit Web API",
            "description": "Fitbit designs products that track everyday health and fitness, empowering and inspiring people to lead healthier, more active lives.",
            "image": "https://www.fitbit.com/images/common/logo_with_trademark.png",
            "humanURL": "https://dev.fitbit.com/",
            "baseURL": "https://api.fitbit.com/",

(33) Pivio

• Pivio [http://pivio.io/] is a tool and a data format [http://pivio.io/docs/#section-dataformat]
  • A small number of mandatory fields (id/name/short_name/type/owner/description)
  • A small number of optional fields
  • Extensions can be added via custom extensions [http://pivio.io/docs/#_custom_extensions]

id: next-generation-print-2342-2413-9189-1990
name: Next Generation Print Service
short_name: NGPS
type: service
owner: Team Goldfinger
description: Prints all kinds of things. Now with 3D printing support.
vcsroot: git://git.vcs.local/UBP
contact: Auric Goldfinger
lifecycle: production
tags:
 - Old
 - Demo
links:
  homepage: http://wiki.local/ubp
  buildchain: http://ci.local/ubp
  api_docs: http://docs.local/ubp-api

(35) Labels as First-Class Concepts

• Standalone API Labels
  • Ability to represent and exchange labels as API-managed resources
  • API labels become part of the standard vocabulary of API design [http://webconcepts.info/]
• Embedded API Labels
  • API description formats may support some set of labels
  • Embedded labels can be mapped to the standalone format
• Labels as APIs
  • Third-party services may provide LaaS (Label as a Service)

(36) 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
• Design a namespace that works across all use cases
  • Simple names (e.g., version) that are managed in an open registry [https://tools.ietf.org/html/draft-wilde-registries]
  • URIs as names for proprietary types to minimize the risk of name clashes

(37) Label Design Spectrum

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

• Complex values (what's the metamodel?)
• Label lifetime (start/end timestamps)
• Label creator (different from labeled API)
• Signed labels (labels as certificates)

(38) Guidelines for API Labels

• Findable labels by exposing them in the API itself
  • labels link from API home document [http://webconcepts.info/specs/IETF/I-D/nottingham-json-home] for discovery
  • Additional discovery for tooling-based and third-party labels
• Readable labels by using a standardized label format
  • Reusable across various APIs and API styles
• Understandable labels by using labels as required/recommended by the guidelines
  • Label types are either well-known and/or managed in a shared registry
  • Label requirements depend on API style and technology
  • Label testing can be integrated into deployment pipelines

(40) API Label Takeaways

• API Landscapes can benefit from API Labels
  • Improve observability and insights and evolve labeling over time
• Decoupling labels from API formats help with label applicability
  • Labels as first-class concepts [Labels as First-Class Concepts (1)] makes them independent from API technology
• Use your own label format and/or join github.com/API-Labels [https://github.com/API-Labels]
  • Help the API community by sharing your scenarios and requirements
• There may be an opportunity for improving the API economy

(41) Labels for Long-Term Landscaping

(42) Thanks! Q&A

• Cesare Pautasso and Erik Wilde, "May Contain Nuts: The Case for API Labels", 14th International Workshop on Engineering Service-Oriented Applications and Cloud Services (WESOACS 2018), Como, Italy, September 2018. ( paper [http://dret.net/netdret/publications#pau18a] / presentation slides [http://www.pautasso.info/talks/2018/2018-WESOACS-APIlabels] )
• API-Labels [https://github.com/API-Labels] organization on GitHub
  • label-format [https://github.com/API-Labels/label-format] repository for the label format
  • API-label-registry [https://github.com/API-Labels/API-label-registry] repository for the registry of API labels
• Slides online: dret.net/lectures/oreilly-sa-2018 [http://dret.net/lectures/oreilly-sa-2018]
  • Me on Twitter: @dret [http://twitter.com/dret]