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

(8) Food Labels

(9) Safety Labels

(10) Label Design and Complexity

(11) OCD? Landscape Management!

(12) Why Do Labels Work?

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

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

• Simple/simplified description of important product aspects
• Supported across large sets of products (sometimes even across categories)
• Defined/assigned/verified/certified by a trusted third party

(14) Labels: Sharing + Loose Coupling

(15) API the APIs

If you want to say something about your API, say it through your API.

• Configuration/description/documentation as code
• Accessible to tooling and automation
• Separate representation and label semantics

(16) Better Descriptions ⇒ Better Search and Use

• Google just (September 2018) launched Google Dataset Search [https://toolbox.google.com/datasetsearch]
  • It is based on dataset descriptions [https://www.blog.google/products/search/making-it-easier-discover-datasets/] which are based on schema.org [https://schema.org/]
• Public description and search helps aggregators (and their users)
• Private description helps internal management and landscaping

(17) API Label Scenarios

• API labels are not intended to replace API descriptions
  • Descriptions are more detailed and complex
• API labels as a way to expose/share information internally
  • Managing labels types/values and trust is relatively easy
• API labels as a way to expose/share information publicly
  • Managing labels types/values and trust becomes more challenging

(18) Get API Labels

(19) Get Certified Labels from 3rd Party

(20) Get Labels Assigned by 3rd Party

(21) Assigned Labels for API Discovery

(22) Declared Labels for API Discovery

(24) API Label Types

• Label types can be registered or extension label types
• Registered label types are managed in an open API label type registry [https://github.com/API-Labels/API-label-registry]
  • Registered types have well-known names that are simple strings
• Extension label types can be used by anybody with no registration required
  • Extension types have self-describing names that are URIs

(25) SPDX [https://spdx.org/] License Values [https://spdx.org/licenses/]

(27) Get API Labels! But How?

(28) API Label Formats

(29) Home Documents for HTTP APIs [https://tools.ietf.org/html/draft-nottingham-json-home]

{
  "api": {
    "title": "Example API",
    "links": {
      "author": "mailto:api-admin@example.com",
      "describedBy": "https://example.com/api-docs/"
    }
  },
  "resources": {
    "tag:me@example.com,2016:widgets": {"href": "/widgets/"},
    "tag:me@example.com,2016:widget": {
      "hrefTemplate": "/widgets/{widget_id}",
      "hrefVars": {"widget_id": "https://example.org/param/widget"},
      "hints": {
        "allow": [
          "GET",
          "PUT",
          "DELETE",
          "PATCH"
        ],
        "formats": {"application/json": {}},
        "acceptPatch": ["application/json-patch+json"],
        "acceptRanges": ["bytes"]
      }
    }
  }
}

(30) Finding Labels

  "api": {
    "title": "Example API",
    "links": {
      "author": "mailto:api-admin@example.com",
      "describedBy": "https://example.com/api-docs/",
      "labels": "https://example.com/labels.json"
    }

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

(32) Labels: Sharing + Loose Coupling

(33) Related Work

• Pivio [http://pivio.io/] for service documentation and discovery
• APIs.json [http://apisjson.org/] for describing API operations
• OpenAPI Info Object [https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#infoObject] and possible extensions
• RAML User Documentation [https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/#user-documentation] and possible extensions

(34) API Labels: Next Steps

• Decoupling labels from specific API styles and descriptions
• Collect use cases and patterns for using API labels
• Converge on a format and establish a registry for shared label types

(35) Additional Resources

• 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
• 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] )
• These slides online: dret.net/lectures/apistrat-2018 [http://dret.net/lectures/apistrat-2018] (slide sources [http://github.com/dret/lectures/tree/master/apistrat-2018])