(3) API are Languages

• APIs allow service providers and consumers to communicate
  • Service providers define the language to be used for service interactions
  • Service consumers use the language to interact with the service
• Interfaces both separate and connect users of the interface
  • Separation means that the interface is self-contained
  • Connection means that the interface is easy to use
• Language design becomes different in complex landscapes
  • Singular APIs derive value from being individually polished products
  • Landscape APIs derive value from maximizing productivity across products

(4) Languages need Standards

• Standards become building blocks of easily usable APIs
  • Each building block reduces design effort and improves understandability
• Building blocks can be used from various areas
  1. General API concepts that can be used uniformly across various APIs
  2. Domain concepts that can be used across APIs for a certain domain
  3. Organizational concepts that make sense for APIs within an organization

(6) Standard Types [https://www.safaribooksonline.com/library/view/restful-web-apis/9781449359713/pr05.html]

• Fiat standards: Why not do it this way?
• Personal standards: I like the way this has been done.
• Corporate standards: Let's try to figure out a way to do this.
• Open standards: Hello everybody! Let's share a way to do this!

(7) How Standards Proliferate

(9) Internet Engineering Task Force (IETF) [http://ietf.org/]

(10) World Wide Web Consortium (W3C) [http://www.w3.org/]

(11) International Organization for Standardization (ISO) [http://www.iso.org/]

(13) Separating Definition and Evolution

• Concepts may be well-defined but with open and evolving value sets
  • Employees may be as simple as listing people who have been on payroll
  • Languages are not easy to find and identify but some consensus is possible
  • Countries are even trickier because of politics and history
• Technical concepts often are easier to identify and manage
  • Registry policies must be well-defined so that management is predictable
  • Registries contain values and usually link to semantic descriptions
  • Sharing values should be the equivalent of sharing concepts

(14) IANA [http://www.iana.org/] Protocol Registries [http://www.iana.org/protocols]

(15) Preventing Value Drift

• Registered values should be stable over time
  • The only allowed semantic update are clarifications or updated specifications
  • Backwards-compatible specifications are essential (the old meaning still holds)
• Registered values should never be reassigned
  • Reassigning values is equivalent to a breaking change in value semantics
  • Once registered, values are defined and their meaning will never change
• Registered values may be marked as being deprecated
  • There may be a registry flag indicating that values should be treated as deprecated
  • Deprecated values may be treated as errors at some point in time
  • Deprecated values can never be reassigned (see above)

(17) Food Labels

(18) Safety Labels

(19) Web Concepts: Specifications [http://webconcepts.info/specs/]

• Specifications define values for existing concepts [Web Concepts: Concepts and Values [http://webconcepts.info/concepts/] (1)]
• RFC 7234 (HTTP/1.1 Caching) [http://webconcepts.info/specs/IETF/RFC/7234] defines new values for three existing Web Concepts:
  • HTTP Cache Directives [http://webconcepts.info/concepts/http-cache-directive/]: max-age [http://webconcepts.info/concepts/http-cache-directive/max-age], max-stale [http://webconcepts.info/concepts/http-cache-directive/max-stale], min-fresh [http://webconcepts.info/concepts/http-cache-directive/min-fresh], must-revalidate [http://webconcepts.info/concepts/http-cache-directive/must-revalidate], no-cache [http://webconcepts.info/concepts/http-cache-directive/no-cache], no-store [http://webconcepts.info/concepts/http-cache-directive/no-store], no-transform [http://webconcepts.info/concepts/http-cache-directive/no-transform], only-if-cached [http://webconcepts.info/concepts/http-cache-directive/only-if-cached], private [http://webconcepts.info/concepts/http-cache-directive/private], proxy-revalidate [http://webconcepts.info/concepts/http-cache-directive/proxy-revalidate], public [http://webconcepts.info/concepts/http-cache-directive/public], s-maxage [http://webconcepts.info/concepts/http-cache-directive/s-maxage]
  • HTTP Header Fields [http://webconcepts.info/concepts/http-header/]: Age [http://webconcepts.info/concepts/http-header/Age], Cache-Control [http://webconcepts.info/concepts/http-header/Cache-Control], Expires [http://webconcepts.info/concepts/http-header/Expires], Pragma [http://webconcepts.info/concepts/http-header/Pragma], Warning [http://webconcepts.info/concepts/http-header/Warning]
  • HTTP Warn Codes [http://webconcepts.info/concepts/http-warn-code/]: 110 [http://webconcepts.info/concepts/http-warn-code/110], 111 [http://webconcepts.info/concepts/http-warn-code/111], 112 [http://webconcepts.info/concepts/http-warn-code/112], 113 [http://webconcepts.info/concepts/http-warn-code/113], 199 [http://webconcepts.info/concepts/http-warn-code/199], 214 [http://webconcepts.info/concepts/http-warn-code/214], 299 [http://webconcepts.info/concepts/http-warn-code/299]
• Specifications add one or more values for one or more concepts
• Specification series [http://webconcepts.info/specs/IETF/] define naming patterns for automated processing

(20) Web Concepts: Concepts and Values [http://webconcepts.info/concepts/]

• Concepts establish a namespace for sharing values with shared meanings
• HTTP Header Fields [http://webconcepts.info/concepts/http-header/] are one concept with currently 200 distinct values
  • The currently listed values are defined in W3C/IETF specifications
  • If required the list could be extended with de-facto standards as well
• Link Relation Types [http://webconcepts.info/concepts/link-relation/] are an extensible and fuzzy concept
  • 123 distinct link relation types have been established as registered values
  • Hypermedia applications often will use private URI-identified relations

(21) Web Concepts Overview

(22) Specification Series

    <primary id="IETF" href="http://www.ietf.org/">
        <name short="IETF">Internet Engineering Task Force</name>
        <secondary id="RFC">
            <name short="RFC">Request for Comments</name>
            <id-pattern>^(\d+)$</id-pattern>
            <md-pattern>$1</md-pattern>
            <name-pattern>RFC $1</name-pattern>
            <uri-pattern>urn:ietf:rfc:$1</uri-pattern>
            <url-pattern>http://tools.ietf.org/html/rfc$1</url-pattern>
        </secondary>
        <secondary id="I-D">
            <name short="I-D">Internet Draft</name>
            <id-pattern>^(.+)$</id-pattern>
            <md-pattern>$1</md-pattern>
            <name-pattern>Internet Draft $1</name-pattern>
            <uri-pattern>urn:ietf:id:$1</uri-pattern>
            <url-pattern>http://tools.ietf.org/html/draft-$1</url-pattern>
        </secondary>
    </primary>

(23) Concept Configuration

    <concept id="http-header">
        <title-singular>HTTP Header Field</title-singular>
        <title-plural>HTTP Header Fields</title-plural>
        <iana-registry>http://www.iana.org/assignments/message-headers/message-headers.xhtml</iana-registry>
    </concept>

    <concept id="http-warn-code">
        <title-singular>HTTP Warn Code</title-singular>
        <title-plural>HTTP Warn Codes</title-plural>
        <iana-registry>https://www.iana.org/assignments/http-warn-codes/http-warn-codes.xhtml</iana-registry>
    </concept>
    <concept id="http-cache-directive">
        <title-singular>HTTP Cache Directive</title-singular>
        <title-plural>HTTP Cache Directives</title-plural>
        <iana-registry>http://www.iana.org/assignments/http-cache-directives/http-cache-directives.xhtml</iana-registry>
    </concept>

(24) Constraining Concepts

• Ignore/remove specifications that you are not interested in
• Ignore/remove specification series that you are not interested in
• Ignore/remove organizations that you are not interested in
• The resulting specifications are your Web Concepts
• They can be one starting point for API guidelines [http://apistylebook.com/]

(25) Custom Concepts

• Add specifications that you are interested in
• Add specification series that you are interested in
• Add organizations that you are interested in
• Anything that has potential for reuse can and should be added
• The resulting specifications are your Web Concepts
• They can be one starting point for API guidelines [http://apistylebook.com/]

(26) Concept Coverage

• Track concept value usage across APIs
• Create a dashboard of concept/value popularity (possibly over time)
• Can be done through code analysis (up to a certain point)
• Probably works better/easier through service fabric instrumentation
• Ideally separate tooling and backed by an API/format for representing usage data

(28) Thanks!

• Slides online: dret.net/lectures/www-2019 [http://dret.net/lectures/www-2019]
• More information about myself:
  • Twitter: @dret [http://twitter.com/dret]
  • LinkedIn: linkedin.com/in/netdret [http://www.linkedin.com/in/netdret]
  • Web page: dret.net/netdret/ [http://dret.net/netdret/]