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

(5) @dret on Twitter/GitHub

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

(7) Microservice Architecture

• Microservice Architecture: Aligning Principles, Practices, and Culture
• Authored by [http://www.apiacademy.co/microservice-architecture-the-oreilly-book/] API Academy [http://www.apiacademy.co/] members Irakli Nadareishvili, Ronnie Mitra, Matt McLarty, and Mike Amundsen
  • Get free electronic version courtesy of CA Technologies [http://transform.ca.com/API-microservice-architecture-oreilly-book.html]
  • Get a hardcopy version [http://shop.oreilly.com/product/0636920050308.do]

(9) What is an API?

• An API is a product
  • APIs are created and designed and developed
  • APIs have typical product lifecycles
• An API provides access to a capability
  • The API is not the interesting thing
  • The value is in the functionality of the API
• An API is a language
  • API users utilize API functionality by accessing the API
  • Using APIs is a conversation between service providers and consumers

(10) API Design

• APIs need to be designed just like any other product
  • Design starts with an architectural style and associated patterns
  • The style sets the framework but leaves a lot of freedom
  • Some design elements can be reused from existing APIs
  • Some design elements have to be created for the new API
• Design works best when it reuses familiar interface concepts
  • For UI design this allows end users to make educated guesses for better UX
  • For API design the same concept of familiarity is helpful for DX

(11) Interface Design

(12) Continuous Architecture

(14) SOAP: The Dark Age

• API design was practiced relatively little
  • Developers exposed implementation internals as Web services
  • Many APIs were exposed from a shared monolithic codebase
• SOAPy SOA promised webby nirvana without delivering
  • The main failure was the lack of focus on loosely coupled implementation
  • Evolution needs ecosystems where individuals can flourish or wane

(15) Microservices: Enlightenment

• The first time enterprise IT gets the Web
  • Decouple implementations for speed and agility at scale
  • Embrace diversity so that teams can focus on solving problems
• What do microservices mean for scale and longevity?
  • Design decisions need context for the best possible products
  • Designing into the void never is the best strategy

(16) The Middle Ground: Guide and Help

• Create Design Guidelines [http://apistylebook.com/design/guidelines/] that teams can use
  • Ideally based on existing practice
  • Ideally continuously changed based on the evolving landscape
• Writing as a form of communication
  • Writing guidelines forces teams to talk about design practices
  • Reading guidelines allows teams to understand the current practice

(17) Language and Design and Culture

• Culture emerges as a set of shared principles and patterns
  • Culture cannot be created from the top-down
  • Culture can be observed and nudged over time
• Design culture for APIs uses shared language building blocks
  • Documenting what APIs and teams are using
  • Helping teams in the API design efforts
• Documenting API design culture is a continuous process
  • Feedback cycle based on practice and design guidance

(19) Concepts that matter on the Web

• Web APIs are always based on shared architectural concepts
  • Some concepts [http://webconcepts.info/concepts/] matter for interaction at the Web level
  • Each concept has a value space for sharing meaning (such as HTTP request methods [http://webconcepts.info/concepts/http-method/])
  • Specifications establishing values are created by organizations [http://webconcepts.info/specs/] (such as HTTP PATCH [http://webconcepts.info/concepts/http-method/PATCH] via IETF [http://webconcepts.info/specs/IETF/]'s RFC [http://webconcepts.info/specs/IETF/RFC/] 5789 [http://webconcepts.info/specs/IETF/RFC/5789])
• Web concepts [http://webconcepts.info/] provides a starter set of concepts and specifications
  • Currently there are 32 concepts with a total of 738 distinct values [http://webconcepts.info/concepts/]
  • These concepts are taken from 268 specifications from 5 organizations [http://webconcepts.info/specs/]
• Web concepts is designed to be usable along two major axes
  1. Adding or removing concepts/values to represent the organizational Web surface
  2. Adding API-level usage to link APIs and the concepts they use

(20) Specifications

 "IETF": {
  "id": "http://webconcepts.info/specs/IETF/",
  "name": "Internet Engineering Task Force",
  "short": "IETF",
  "series": [{
   "I-D": {
    "id": "http://webconcepts.info/specs/IETF/I-D/",
    "name": "Internet Draft",
    "short": "I-D",
    "specs": [{
     "amundsen-richardson-foster-alps": {
      "id": "http://webconcepts.info/specs/IETF/I-D/amundsen-richardson-foster-alps",
      "title": "Application-Level Profile Semantics (ALPS)",
      "name": "Internet Draft amundsen-richardson-foster-alps",
      "URI": "urn:ietf:id:amundsen-richardson-foster-alps",
      "URL": "http://tools.ietf.org/html/draft-amundsen-richardson-foster-alps",
      "abstract": "This document describes ALPS, a data format for defining simple descriptions of application-level semantics, similar in complexity to HTML microformats. An ALPS document can be used as a profile to explain the application semantics of a document with an application-agnostic media type (such as HTML, HAL, Collection+JSON, Siren, etc.). This increases the reusability of profile documents across media types.",
      "concepts": [{
       "http://webconcepts.info/concepts/media-type/": "http://webconcepts.info/concepts/media-type/application/alps+json" }, {
       "http://webconcepts.info/concepts/media-type/": "http://webconcepts.info/concepts/media-type/application/alps+xml" }]}},{

(21) Concepts

    { "concept" : "http-authentication-scheme",
      "id" : "http:\/\/webconcepts.info\/concepts\/http-authentication-scheme\/",
      "name-singular" : "HTTP Authentication Scheme",
      "name-plural" : "HTTP Authentication Schemes",
      "registry" : "http:\/\/www.iana.org\/assignments\/http-authschemes\/http-authschemes.xhtml#authschemes",
      "values" : 
      [ 
        { "value" : "Basic",
          "concept" : "http:\/\/webconcepts.info\/concepts\/http-authentication-scheme\/",
          "id" : "http:\/\/webconcepts.info\/concepts\/http-authentication-scheme\/Basic",
          "details" : 
          [ 
            { "description" : "The Basic authentication scheme is based on the model that the client needs to authenticate itself with a user-id and a password for each protection space (\"realm\"). The realm value is a free-form string that can only be compared for equality with other realms on that server.",
              "documentation" : "http:\/\/tools.ietf.org\/html\/rfc7617#section-2",
              "specification" : "http:\/\/webconcepts.info\/specs\/IETF\/RFC\/7617",
              "spec-name" : "RFC 7617" } ] },
        

(23) Resource Representations

• APIs need some way to represent the information that is being exchanged
  • The API style dictates the framework for the representations
  • Individual APIs always need domain vocabularies
• Keeping track of vocabularies becomes the domain inventory for the entire organization
  • Your APIs are your EIM

(24) Reusing Representations

• Using application/json [http://webconcepts.info/concepts/media-type/application/json] helps to not reinvent the wheel
• Many core standards are horizontal in nature
• Some domains may have vertical standards they can reuse
• Even vertical standards often can be extended for service-specific features

(25) Adding Representations

• Adding representations can be done with new values for existing concepts
  • Using media types [http://webconcepts.info/concepts/media-type/application/json] as one way of doing it
  • Using profiles [http://webconcepts.info/concepts/profile-uri/] is a lightweight way of specializing media types
  • Using XML namespaces [http://webconcepts.info/concepts/xml-ns/] is a different way of identifying vocabularies
• It also is possible to add new concepts that are not currently part of Web concepts [http://webconcepts.info/concepts/]

(26) Mixing Representations

• Parts of APIs often can be covered by vertical standards
  • Represent problem reports in APIs with application/problem+json [http://webconcepts.info/concepts/media-type/application/problem+json]
  • Represent status information about APIs with application/vnd.health+json [http://webconcepts.info/concepts/media-type/application/vnd.health+json]
• APIs always are a mixed design of existing and new language elements
  • Using existing language elements helps understanding but constrains the design space
  • Inventing new language elements allows design freedom but is harder for API users

(28) But What Now? Help Web Concepts!

• Web concepts is a starting point of shared standards
  • Meant to represent ongoing developments in the global community
  • Not meant to represent individual preferences or additions or usage
• Make Web concepts easier to use, reuse, and tweak
  • Fork Web concepts [https://github.com/dret/webconcepts] and remove unused building blocks
  • Add building blocks in the form of other standards or inhouse definitions
• Make Web concepts easier to relate to usage information
  • Develop ways to capture and reuse concept usage for individual APIs
  • Collect and present usage across APIs to track landscape evolution

(29) Thanks! Q&A

• Slides online: dret.net/lectures/api-days-paris-2018 [http://dret.net/lectures/api-days-paris-2018]
• Slide sources: dret/lectures [http://github.com/dret/lectures/tree/master/api-days-paris-2018] on GitHub [http://github.com/]
• Me: http://dret.net/netdret/ [http://dret.net/netdret/]
• Twitter: @dret [http://twitter.com/dret]