(22) Versioning in Practice

• Version numbers have an almost mythical role in IT
  • But often they are only useful for signaling continuity or breakage points
  • Most things work or break in a binary way (or simply refuse to even try)
• Compatibility comes in two basic flavors (one easier, one harder)
  • Backwards compatibility means to work with older components
  • Forward compatibility means to work with more advanced components
• The Web has good rules to support both compatibility types
  • Backwards compatibility: New browser accessing older content
  • Forward compatibility: Old browser accessing newer content

(23) Versioning Breaks Things

(24) Plan for Evolution

• Planning for evolution means to reduce pain in the future
  • No immediate benefits other than doing the right thing
  • Modest effort when part of the API design process and culture
• Extensibility should be part of the API design culture
  • Each API must have and document a plan for API evolution
  • The simplest possible plan may be to never change the API
• Extensibility should be made easy for API consumers
  • Provide test cases that simulate correct/incorrect API extensions
  • Provide feature flags so that services can enter test mode

(26) Meaningful Core Semantics

• The core of the API allows clients to have meaningful interactions
  • The starting point of an API should be meaningful and complete
• The core of the API is robust over time
  • Anything that is added to the core does not change the core semantics
• Anything that is not part of the core can be safely ignored
  • mustIgnore semantics allow safe interactions beyond closely coordinated groups

(27) Well-Defined Extension Points

• APIs should be clear about where extensions are allowed
  • API metamodels often decide where (potential) extension points are
  • API schemas/definitions should further narrow down where extensions are allowed
• API tests can make sure that the extension points are properly implemented
  • Extensions in allowed places are ignored and tests should succeed
  • Extensions in other places should raise errors about malformed content
• Extension points are interesting to support in generic software
  • Monitoring can report which and where extensions are being used
  • Libraries can make it easy to create/parse extension data

(28) Well-Defined Processing Model

• Extensions are well-defined and their handling is well-defined as well
  • Extension points make it clear where to expect extensions
  • Processing models make it clear what to do with extensions
• mustIgnore is a popular and good choice for extension processing
  • Some formats allow extensions to declare their processing model (such as mustUnderstand)
  • HTML has a rule of ignoring unknown elements but processing their content
• How to learn about extensions is a different matter
  • If an API evolves along a single path it may be as simple as looking along that path
  • If an API is used in more complex ways [https://tools.ietf.org/html/draft-wilde-registries] a registry may be a way to find extensions

(30) Extensibility of Content

• Extending content can be done by additive changes to the content
  • Adding properties to the existing content model
  • Limiting properties to a more constraining appearance/value model
• Extension can never change the semantics of existing content
  • Ignoring extensions always must be a safe thing to do
  • Dependencies across extensions should be avoided if possible
• Specifying extension points depends on the representation format

(31) XML Content Extension

<address>
  <name>Peter Pan</name>
  <street>Kensington Gardens 42</street>
  <city>2076 Neverland</city>
</address>

<address>
  <name>Harry Potter</name>
  <street>4 Privet Drive</street>
  <city>Little Whinging</city>
  <title>Wizard</title>
</address>

(32) XML Content Extension: XSD Schema

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="address">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="name" type="xs:string"/>
        <xs:element name="street" type="xs:string"/>
        <xs:element name="city" type="xs:string"/>
        <xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

(33) JSON Content Extension

{"address": {
  "name": "Peter Pan",
  "street": "Kensington Gardens 42",
  "city": "2076 Neverland"
}}

{"address": {
  "name": "Harry Potter",
  "street": "4 Privet Drive",
  "city": "Little Whinging",
  "title": "Wizard"
}}

(34) Extensibility of Controls

• Controls expose new paths of the workflow available to clients
  • New paths should not have any impact on existing paths
  • Existing clients should ignore those paths
• Hypermedia formats should be based on controls being an open set
  • Specifics on how to add and handle extensions depend on the format

(35) Extending Controls in HAL

            "_links": {
                "self": { "href": "/orders/124" },
                "http://example.com/docs/rels/basket": { "href": "/baskets/97213" },
                "http://example.com/docs/rels/customer": { "href": "/customers/12369" }
            },
            "total": 20.00,
            "currency": "USD",
            "status": "processing"

{
  "_links": {
    "self": {"href": "/orders/124"},
    "http://example.com/docs/rels/basket": {"href": "/baskets/97213"},
    "http://example.com/docs/rels/customer": {"href": "/customers/12369"},
    "http://example.com/docs/rels/cancel": {"href": "cancel"}
  },
  "total": 20,
  "currency": "USD",
  "status": "processing"
}

(37) Semantic Versioning [http://semver.org/]

• Semantic Versioning [http://semver.org/] standardizes the meaning of version numbers
• Version numbers follow the MAJOR.MINOR.PATCH pattern and the following rules
  • Increase MAJOR version for incompatible API changes
  • Increase MINOR version for adding functionality in a backwards-compatible manner
  • Increase PATCH version for making backwards-compatible bug fixes
• Mostly about how to name implementation artifacts but also applicable to APIs
  • Exposing detailed version/patch information is a potential security risk
  • For well-designed APIs only MINOR may make sense to expose

(38) Service vs. API Version

• Service versions may be internal information only
  • Implementation information does not have to show up in the API
  • For internal/trusted/open cases service and API may be the same thing
• API versions are about changes that may affect consumers
  • PATCH does not change API design or behavior apart from increasing quality
  • MINOR does change API behavior but in a safe way
  • MAJOR changes API behavior in ways that require client adaptations
• PATCH/MINOR may make sense to expose inside the API
• MAJOR means that there is a different API for the same service

(39) Identifying Versions

• Versioning may be necessary when the extension model is not working anymore
• Three main ways how to distinguish between versions at the API level
  • Make version numbers part of the resource URI: http://example.org/api/v2/
  • Use specific HTTP headers: API-Version: 2.0.0
  • Use media types: Accept: application/vnd.example.org.v2+json
• All of these have side-effects which have to be balanced
  • New URIs change resource identity which may result in data integration problems
  • Custom headers are specific for a service and hard to use in the general Web fabric
  • Media types often are not used by APIs or the clients consuming them
• Most APIs choose URI-based versioning and introduce new API identity
  • Versioning at this level is little more than keeping the API brand
  • Version numbers can be used anywhere in the URI path

(40) Linking Versions

• Communicating versions via links works better than naming schemes
  • APIs remain self-contained as long as consumers are working with one version
  • APIs are brought into context when consumers want versioning information
• RFC 5829 [https://tools.ietf.org/html/rfc5829] defines link relations for simple version navigation
  • successor-version links to the newer version of the API
  • latest-version links to the newest version of the API
  • predecessor-version links to the older version of the API
  • version-history links to a resource about the version history
• Plays well with home documents and their role for an API
  • APIs share home documents or at least version histories across versions
  • Versioning links are used to allow navigation across all API versions

(42) Signaling API End-of-Life

• APIs can change in terms of features and will be decommissioned at some point
  • Robust extensibility [http://dret.typepad.com/dretblog/2016/04/robust-extensibility.html] helps to facilitate non-breaking API changes
  • Hypermedia helps as a pattern to move extensibility beyond data models
  • Semantic versioning [http://semver.org/] may be used to keep track of API changes
  • HTTP Sunsetting [http://dret.typepad.com/dretblog/2015/08/http-sunset-header.html] can be used to signal upcoming sunsets on the HTTP level [http://webconcepts.info/concepts/http-header/Sunset]
• One possible requirement is that APIs must support Sunset [http://webconcepts.info/concepts/http-header/Sunset]
  • Services must document/describe the support of Sunset
  • Services may implement Sunset any way they like
  • The simplest option may be Sunset policies on a gateway