(3) Web Links are Typed Links

• Links are possible paths a client can follow to accomplish a goal
  • Some links are typed through HTML markup (<img>, <form>, <link rel="">)
  • Many links are typed for human users (<a>)
• Links show the way but do not determine the destination
  • Images can use various formats represented at runtime through the media type
  • Clients can specify capabilities/preferences via HTTP
• Hypermedia as the engine of application state (HATEOAS)
  • Clients start at a resource and with a certain goal
  • They follow links based on resources they encounter and choices they make
  • Application state is a result of a series of interactions

(4) Web Linking for APIs

• Web Linking [http://webconcepts.info/specs/IETF/RFC/8288] takes linking to the HTTP level
  • Link HTTP Header [http://www.webconcepts.info/concepts/http-headers/Link] for links on the HTTP level
  • All links are typed and types are either registered or defined/used by individual users
  • The link relations registry [http://www.iana.org/assignments/link-relations/link-relations.xhtml] establishes a shared set of meaningful link types
• Documenting hypermedia APIs always means to document all link relation types
  • Registered link types have to be put/described in the context of the API
  • Extension link types must be completely documented in the context of the API

(5) Registered Link Types

• Well-known link relation types are registered with IANA
  • Registration can be done be anybody and follows a simple process
  • Ideally the registry should reflect shared practices by the community
• Registered link relation types are simple strings
  • Any simple name that is used should be described in the registry
  • For specific/proprietary types it is possible to use extension relation types

(6) Extension Link Types

• Non-registered link relation type can be invented and used by everybody
  • These extension link relation types must be named with a URI
  • Optionally, the URI may provide documentation for the link relation type
• Many hypermedia APIs use a mix of registered and extension types
  • Use registered type when the registry provides ones that are a good fit
  • Use extension types when no good fits can be found in the registry

(8) Hypermedia and Affordances

When I say hypertext, I mean the simultaneous presentation of information and controls such that the information becomes the affordance through which the user (or automaton) obtains choices and selects actions. [http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven] (Roy Fielding [https://en.wikipedia.org/wiki/Roy_Fielding])

(9) Hypermedia and Workflows

• Hypermedia combines state representation and possible further interactions
  • Resource state allows clients to understand the current content
  • Links allow clients to learn about the possible next steps
  • Clients select and follow a link based on their application goals
• Workflows are represented by providing navigation options (affordances)
  • Making it easier for clients to be driven by available options
  • Seamless fabric of navigation across individual APIs

(10) Hypermedia and API Evolution

• Extensibility generally is a good idea for APIs
  • Eliminates or reduces the need to do potentially expensive versioning
• Hypermedia representations by definition combine data and control elements
  • Data extensibility results in the usual benefits of allowing representations to evolve
  • Control extensibility results in the ability to add new workflow paths
• Hypermedia-based evolution has many patterns to choose from
  • Incremental additions can show up as new links in extension slots
  • Complete new APIs can be advertised as new start resources in home documents

(12) Representing Links

• Hypermedia always is about mixing data and controls in representations
  • Some scenarios can strictly separate the links and the data
  • Other scenarios need links to be embedded in data to make sense
• At the very minimum links need a target URI to identify the link target
  • Typically links are typed implicitly or explicitly for differentiation
  • Links may also be decorated with hints for additional information
• Links representations are the information that clients have to make decisions
  • Some link hints may help to choose between navigation paths
  • Some link hints may be optimizations that duplicate/mirror HTTP mechanisms
• Links may also be represented in the HTTP Link header field [http://webconcepts.info/concepts/http-header/Link]

(13) Link Representation (JSON Feed Format)

{
    "version": "https://jsonfeed.org/version/1",
    "title": "My Example Feed",
    "home_page_url": "https://example.org/",
    "feed_url": "https://example.org/feed.json",
    "items": [
        {
            "id": "2",
            "content_text": "This is a second item.",
            "url": "https://example.org/second-item"
        },
        {
            "id": "1",
            "content_html": "<p>Hello, world!</p>",
            "url": "https://example.org/initial-post"
        }
    ]
}

(14) Typed Links

• Links represents navigational options for clients
  • APIs include links that are advertised based on service and state
  • Clients choose links based on application state and goals
• Link typing on the Web often is done using RFC 8288 Web Linking [http://webconcepts.info/specs/IETF/RFC/8288]
  • Registered types [http://tools.ietf.org/html/rfc8288#section-2.1.1] are simple strings using well-known values [https://www.iana.org/assignments/link-relations/link-relations.xhtml]
  • Extension types [http://tools.ietf.org/html/rfc8288#section-2.1.2] are URIs which might choose to self-document their meaning
• Registered types [http://webconcepts.info/concepts/link-relation/] have documented but fuzzy meaning
  • APIs need to document which types they use and what they mean
  • Reusing existing types makes the API language easier to understand and use

(15) Typed Links (HAL Format)

    "currentlyProcessing": 14,
    "shippedToday": 20,
    "_embedded": {
        "http://example.com/docs/rels/order": [{
            "_links": {
                "self": { "href": "/orders/123" },
                "http://example.com/docs/rels/basket": { "href": "/baskets/98712" },
                "http://example.com/docs/rels/customer": { "href": "/customers/7809" }
            },
            "total": 30.00,
            "currency": "USD",
            "status": "shipped"
        }, {
            "_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"

(17) Specific Hypermedia Formats

• Any format that mixes control and data is a hypermedia format
  • Standard issues of how to define representations
  • Additional issues of where and how to embed links as controls
• Depending on the metamodel and schema language varying support
  • Not everybody likes using schema languages
  • Many schema languages are focusing on grammars and data types
  • Some schema languages at least have data types for URIs
  • Few schema languages have explicit support for hypermedia

(18) Generic Hypermedia Formats

• Instead of designing hypermedia it's possible to use existing formats
  • Generic formats often provide little more than data/control separation
  • Domain focus results in semi-generic formats such as collection formats
• Hypermedia is more a pattern than it is format or technology
  • Specific technologies may come with more constraints than benefits
  • Never underestimate the benefits of reusing shared languages
• So far there is no clear trend towards a common generic format

(20) The Web Pattern

• Hypermedia is a pattern mixing data and controls
• Hypermedia provides a good foundation for API evolvability
• Clients need a more data-driven control flow

(21) Thanks! Q&A

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