Introduction

Outline (Introduction)

Introduction [2]
Linkset Motivation [7]
RFC 9264 [2]
Example: GS1 Digital Link [4]
Conclusions [3]

Introduction Erik Wilde (@dret): Linking for Fun and Profit: Using Linksets in APIs

(3) Axway [https://www.axway.com] Catalysts [https://catalysts.axway.com]

Small team of experts in the digital transformation and API space
- Help customers to make good decisions on their API journey
- Move the community of API practitioners and their practices forward
Team members are distributed globally
- Emmanuel Methivier: @e_methivier [https://twitter.com/e_methivier]
- Brian Otten: @bottencatalyst [https://twitter.com/bottencatalyst]
- Eyal Sivan: @mropenbanking [https://twitter.com/mropenbanking]
- Erik Wilde: @dret [https://twitter.com/dret]

Introduction Erik Wilde (@dret): Linking for Fun and Profit: Using Linksets in APIs

(4) Erik Wilde (`@dret`) [https://twitter.com/dret]

Linkset MotivationHTTP APIs

Outline (Linkset Motivation)

Introduction [2]
Linkset Motivation [7]
RFC 9264 [2]
Example: GS1 Digital Link [4]
Conclusions [3]

Linkset Motivation Erik Wilde (@dret): Linking for Fun and Profit: Using Linksets in APIs

(6) Building Blocks for HTTP APIs [https://datatracker.ietf.org/wg/httpapi/about/]

Complementing the HTTP [https://datatracker.ietf.org/wg/http/about/] working group
Focusing on non-browser HTTP scenarios
Provide building blocks instead of specific domain solutions
Established in 2020

Linkset Motivation Erik Wilde (@dret): Linking for Fun and Profit: Using Linksets in APIs

(7) One Model To Link Them All

Linking on the Web started with predefined HTML links
- General-purpose links with <a href="…">anchors</a> and page-level <link/>
- Special-purpose links (<img/>, <form/>, <blockquote/>, …)
Linking on the API Web needs link types and link representations
- Web Links are typed 1:1 connections with optional target attributes [https://datatracker.ietf.org/doc/html/rfc8288#section-2]
- Web Links can be represented independently of the media type
RFC 8288 [https://www.rfc-editor.org/rfc/rfc8288] (formerly RFC 5988 [https://www.rfc-editor.org/rfc/rfc5988]) defines the Link [https://www.rfc-editor.org/rfc/rfc8288#section-3] HTTP header field

Linkset Motivation Erik Wilde (@dret): Linking for Fun and Profit: Using Linksets in APIs

(8) Link Example

HTTP/1.1 200 OK
Date: Mon, 12 Aug 2019 10:35:51 GMT
Server: Apache-Coyote/1.1
Content-Type: application/json
Content-Length: 1023
Link: <https://authors.example.net/johndoe>; rel="author"; type="application/rdf+xml", <https://example.org/resource1?version=3>; rel="latest-version"; type="text/html", <https://example.org/resource1?version=2>; rel="predecessor-version"; type="text/html"; anchor="https://example.org/resource1?version=3", <https://example.org/resource1?version=1>; rel="predecessor-version"; type="text/html"; anchor="https://example.org/resource1?version=2", <https://example.org/resource1?version=1>; rel="memento"; type="text/html"; datetime="Thu, 13 Jun 2019 09:34:33 GMT", <https://example.org/resource1?version=2>; rel="memento"; type="text/html"; datetime="Sun, 21 Jul 2019 12:22:04 GMT", <https://authors.example.net/alice>; rel="author"; anchor="https://example.org/resource1#comment=1"

link.txt

Linkset Motivation Erik Wilde (@dret): Linking for Fun and Profit: Using Linksets in APIs

(9) Linkset Example

HTTP/1.1 200 OK
Date: Mon, 12 Aug 2019 10:35:51 GMT
Server: Apache-Coyote/1.1
Content-Type: application/linkset
Content-Length: 1023

<https://authors.example.net/johndoe>
   ; rel="author"
   ; type="application/rdf+xml"
   ; anchor="https://example.org/resource1",
<https://example.org/resource1?version=3>
   ; rel="latest-version"
   ; type="text/html"
   ; anchor="https://example.org/resource1",
<https://example.org/resource1?version=2>
   ; rel="predecessor-version"
   ; type="text/html"
   ; anchor="https://example.org/resource1?version=3",
<https://example.org/resource1?version=1>
   ; rel="predecessor-version"
   ; type="text/html"
   ; anchor="https://example.org/resource1?version=2",
<https://example.org/resource1?version=1>
   ; rel="memento"
   ; type="text/html"
   ; datetime="Thu, 13 Jun 2019 09:34:33 GMT"
   ; anchor="https://example.org/resource1",
<https://example.org/resource1?version=2>
   ; rel="memento"
   ; type="text/html"
   ; datetime="Sun, 21 Jul 2019 12:22:04 GMT"
   ; anchor="https://example.org/resource1",
<https://authors.example.net/alice>
   ; rel="author"
   ; anchor="https://example.org/resource1#comment=1"

linkset.txt

Linkset Motivation Erik Wilde (@dret): Linking for Fun and Profit: Using Linksets in APIs

(10) Linkset Example (JSON)

HTTP/1.1 200 OK
Date: Mon, 12 Aug 2019 10:46:22 GMT
Server: Apache-Coyote/1.1
Content-Type: application/linkset+json
Content-Length: 1246

{ "linkset":
  [
    { "anchor": "https://example.org/resource1",
      "author": [
        { "href": "https://authors.example.net/johndoe",
          "type": "application/rdf+xml"
        }
      ],
      "memento": [
        { "href": "https://example.org/resource1?version=1",
          "type": "text/html",
          "datetime": "Thu, 13 Jun 2019 09:34:33 GMT"
        },
        { "href": "https://example.org/resource1?version=2",
          "type": "text/html",
          "datetime": "Sun, 21 Jul 2019 12:22:04 GMT"
        }
      ],
      "latest-version": [
        { "href": "https://example.org/resource1?version=3",
          "type": "text/html"
        }
      ]
    },
    { "anchor": "https://example.org/resource1?version=3",
      "predecessor-version": [
        { "href": "https://example.org/resource1?version=2",
          "type": "text/html"
        }
      ]
    },
    { "anchor": "https://example.org/resource1?version=2",
      "predecessor-version": [
        { "href": "https://example.org/resource1?version=1",
          "type": "text/html"
        }
      ]
    },
    { "anchor": "https://example.org/resource1#comment=1",
      "author": [
        { "href": "https://authors.example.net/alice"}
      ]
    }
  ]
}

linkset+json.txt

Linkset Motivation Erik Wilde (@dret): Linking for Fun and Profit: Using Linksets in APIs

(11) Too Many Links

Heavily interlinked datasets can result in many outgoing links
HTTP header fields are not intended to carry a lot of data
Representing all links is more robust as a resource

Linkset Motivation Erik Wilde (@dret): Linking for Fun and Profit: Using Linksets in APIs

(12) Third Party Links

Discovering links can be useful in a variety of ways
- As part of a resource as an outbound link
- As relevant for a resource as an inbound link
- As an inbound link but provided not as part of the resource
APIs in these scenarios can benefit from linkset representations

RFC 9264

Outline (RFC 9264)

Introduction [2]
Linkset Motivation [7]
RFC 9264 [2]
Example: GS1 Digital Link [4]
Conclusions [3]

RFC 9264 Erik Wilde (@dret): Linking for Fun and Profit: Using Linksets in APIs

(14) Linkset History

Published versions: 23 (12/2016-07/2022)
History & collaboration
- Datatracker: draft-ietf-httpapi-linkset [https://datatracker.ietf.org/doc/draft-ietf-httpapi-linkset]
- Repo: github.com/ietf-wg-httpapi/linkset [https://github.com/ietf-wg-httpapi/linkset]

RFC 9264 Erik Wilde (@dret): Linking for Fun and Profit: Using Linksets in APIs

(15) RFC 9264: What's in the Specification?

application/linkset media type for linksets using HTTP Link syntax [https://www.rfc-editor.org/rfc/rfc9264#name-http-link-document-format-a]
- Represent a linkset resource in RFC 8288 syntax
application/linkset+json media type for linksets using JSON syntax [https://www.rfc-editor.org/rfc/rfc9264#name-json-document-format-applic]
- Represent a linkset resource in JSON syntax
profile media type parameter for both linkset media types [https://www.rfc-editor.org/rfc/rfc9264#name-the-profile-parameter-for-m]
- Allow for linksets to be used with profiles (RFC 6906)
linkset link relation type for linking to linksets [https://www.rfc-editor.org/rfc/rfc9264#name-the-linkset-relation-type-f]
- Allow typed links to express the fact that they're identifying a linkset

Example: GS1 Digital Link

Outline (Example: GS1 Digital Link)

Introduction [2]
Linkset Motivation [7]
RFC 9264 [2]
Example: GS1 Digital Link [4]
Conclusions [3]

Example: GS1 Digital Link Erik Wilde (@dret): Linking for Fun and Profit: Using Linksets in APIs

(17) GS1: Barcodes for Every Thing

Example: GS1 Digital Link Erik Wilde (@dret): Linking for Fun and Profit: Using Linksets in APIs

(18) Barcodes are going 2D

Combine offline and online capabilities using URI Templates
https://id.dalgiardino.com/01/9506000134352 [https://id.dalgiardino.com/01/9506000134352]
- Brand domain name: id.dalgiardino.com
- Product identifier (GTIN): 9506000134352

Example: GS1 Digital Link Erik Wilde (@dret): Linking for Fun and Profit: Using Linksets in APIs

(19) Product Page for Humans

Example: GS1 Digital Link Erik Wilde (@dret): Linking for Fun and Profit: Using Linksets in APIs

(20) Product Linkset for Machines

$ curl -H "Accept: application/linkset+json" https://id.gs1.org/01/09506000134352

{
  "linkset": {
    "anchor": "https://id.gs1.org/01/09506000134352",
    "itemDescription": "Dal Giardino Risotto Rice with Musrooms 411 gr",
    "https://gs1.org/voc/defaultLink": [
      {
        "href": "https://dalgiardino.com/risotto-rice-with-mushrooms/",
        "title": "Product information"
      }
    ],
    "https://gs1.org/voc/defaultLinkMulti": [
      {
        "href": "https://dalgiardino.com/risotto-rice-with-mushrooms/",
        "title": "Product information",
        "type": "text/html",
        "hreflang": [ "en" ]
      },
      {
        "href": "https://dalgiardino.com/risotto-rice-with-mushrooms/index.html.es",
        "title": "Información del Producto",
        "type": "text/html",
        "hreflang": [ "es" ]
      },
      {
        "href": "https://dalgiardino.com/risotto-rice-with-mushrooms/index.html.ja",
        "title": "Product information",
        "type": "text/html",
        "hreflang": [ "ja" ]
      },
      {
        "href": "https://dalgiardino.com/risotto-rice-with-mushrooms/index.html.vi",
        "title": "Trang thông tin sản phẩm",
        "type": "text/html",
        "hreflang": [ "vi" ]
      }
    ],
    "https://gs1.org/voc/hasRetailers": [
      {
        "href": "https://dalgiardino.com/where-to-buy/",
        "title": "Where to buy",
        "type": "text/html",
        "hreflang": [ "en" ]
      },
      {
        "href": "https://dalgiardino.com/where-to-buy/index.html.es",
        "title": "Donde comprar Dal Giardino",
        "type": "text/html",
        "hreflang": [ "es" ]
      },
      {
        "href": "https://dalgiardino.com/where-to-buy/index.html.vi",
        "title": "Nơi bán",
        "type": "text/html",
        "hreflang": [ "vi" ]
      }
    ],
    "https://gs1.org/voc/pip": [
      {
        "href": "https://dalgiardino.com/risotto-rice-with-mushrooms/",
        "title": "Product information",
        "type": "text/html",
        "hreflang": [ "en" ]
      },
      {
        "href": "https://dalgiardino.com/risotto-rice-with-mushrooms/index.html.es",
        "title": "Información del Producto",
        "type": "text/html",
        "hreflang": [ "es" ]
      },
      {
        "href": "https://dalgiardino.com/risotto-rice-with-mushrooms/index.html.ja",
        "title": "Product information",
        "type": "text/html",
        "hreflang": [ "ja" ]
      },
      {
        "href": "https://dalgiardino.com/risotto-rice-with-mushrooms/index.html.vi",
        "title": "Trang thông tin sản phẩm",
        "type": "text/html",
        "hreflang": [ "vi" ]
      }
    ],
    "https://gs1.org/voc/recipeInfo": [
      {
        "href": "https://dalgiardino.com/mushroom-squash-risotto/",
        "title": "Wild Mushroom And Butternut Squash Risotto",
        "type": "text/html",
        "hreflang": [ "en" ]
      },
      {
        "href": "https://dalgiardino.com/mushroom-squash-risotto/index.html.es",
        "title": "Recetas",
        "type": "text/html",
        "hreflang": [ "es" ]
      },
      {
        "href": "https://dalgiardino.com/mushroom-squash-risotto/index.html.ja",
        "title": "キノコと砕いたバターナッツ入りのリゾット",
        "type": "text/html",
        "hreflang": [
          "ja"
        ]
      }
    ],
    "https://gs1.org/voc/sustainabilityInfo": [
      {
        "href": "https://dalgiardino.com/about/",
        "title": "About Dal Giardino",
        "type": "text/html",
        "hreflang": [
          "en"
        ]
      },
      {
        "href": "https://dalgiardino.com/about/index.html.es",
        "title": "Sobre Dal Giardino",
        "type": "text/html",
        "hreflang": [
          "es"
        ]
      },
      {
        "href": "https://dalgiardino.com/about/index.html.vi",
        "title": "Phát triển bền vững và t",
        "type": "text/html",
        "hreflang": [
          "vi"
        ]
      }
    ]
  }
}

dal-giardino-linkset.json

Conclusions

Outline (Conclusions)

Introduction [2]
Linkset Motivation [7]
RFC 9264 [2]
Example: GS1 Digital Link [4]
Conclusions [3]

Conclusions Erik Wilde (@dret): Linking for Fun and Profit: Using Linksets in APIs

(22) Keep Calm and Design APIs!

Conclusions Erik Wilde (@dret): Linking for Fun and Profit: Using Linksets in APIs

(23) Thank you for your support!

Co-author: Herbert van de Sompel [https://twitter.com/hvdsomp]
Early adopter: Phil Archer [https://twitter.com/philarcher1] (GS1)
Support group: Building Blocks for HTTP APIs [https://datatracker.ietf.org/wg/httpapi/about/] (IETF)
Supporting grants: StandICT [https://www.standict.eu/] (EU)
Everybody in the RFC's Acknowledgements section [https://www.rfc-editor.org/rfc/rfc9264.html#name-acknowledgements]

Conclusions Erik Wilde (@dret): Linking for Fun and Profit: Using Linksets in APIs

(24) Thank You!

Slides online: dret.net/lectures/asc-2022/ [http://dret.net/lectures/asc-2022/]
More information about myself:
- Twitter: @dret [https://twitter.com/dret]
- youtube.com/ErikWilde [https://www.youtube.com/ErikWilde]
- linkedin.com/in/erikwilde [https://www.linkedin.com/in/erikwilde]

Linking for Fun and Profit: Using Linksets in APIs

API Specifications Conference (ASC) 2022 [https://events.linuxfoundation.org/openapi-asc/]

Erik Wilde (@dret)
Axway Catalyst

September 20, 2022

Contents

Introduction

Outline (Introduction)

(3) Axway [https://www.axway.com] Catalysts [https://catalysts.axway.com]

(4) Erik Wilde (`@dret`) [https://twitter.com/dret]

Linkset MotivationHTTP APIs

Outline (Linkset Motivation)

(6) Building Blocks for HTTP APIs [https://datatracker.ietf.org/wg/httpapi/about/]

(7) One Model To Link Them All

(8) Link Example

(9) Linkset Example

(10) Linkset Example (JSON)

(11) Too Many Links

(12) Third Party Links

RFC 9264

Outline (RFC 9264)

(14) Linkset History

(15) RFC 9264: What's in the Specification?

Example: GS1 Digital Link

Outline (Example: GS1 Digital Link)

(17) GS1: Barcodes for Every Thing

(18) Barcodes are going 2D

(19) Product Page for Humans

(20) Product Linkset for Machines

Conclusions

Outline (Conclusions)

(22) Keep Calm and Design APIs!

(23) Thank you for your support!

(24) Thank You!

Linking for Fun and Profit: Using Linksets in APIs

API Specifications Conference (ASC) 2022 [https://events.linuxfoundation.org/openapi-asc/]

Erik Wilde (@dret)Axway Catalyst

September 20, 2022

Contents

Introduction

Outline (Introduction)

(3) Axway [https://www.axway.com] Catalysts [https://catalysts.axway.com]

(4) Erik Wilde (@dret) [https://twitter.com/dret]

Linkset MotivationHTTP APIs

Outline (Linkset Motivation)

(6) Building Blocks for HTTP APIs [https://datatracker.ietf.org/wg/httpapi/about/]

(7) One Model To Link Them All

(8) Link Example

(9) Linkset Example

(10) Linkset Example (JSON)

(11) Too Many Links

(12) Third Party Links

RFC 9264

Outline (RFC 9264)

(14) Linkset History

(15) RFC 9264: What's in the Specification?

Example: GS1 Digital Link

Outline (Example: GS1 Digital Link)

(17) GS1: Barcodes for Every Thing

(18) Barcodes are going 2D

(19) Product Page for Humans

(20) Product Linkset for Machines

Conclusions

Outline (Conclusions)

(22) Keep Calm and Design APIs!

(23) Thank you for your support!

(24) Thank You!

Erik Wilde (@dret)
Axway Catalyst

(4) Erik Wilde (`@dret`) [https://twitter.com/dret]