(3) Erik Wilde (@dret) [http://twitter.com/dret]

(5) Deprecation: Motivation

I-D: draft-dalal-deprecation-header [https://datatracker.ietf.org/doc/draft-dalal-deprecation-header]

Co-author: Sanjay Dalal

• The Sunset Header Field [https://tools.ietf.org/html/rfc8594] is useful but has limited semantics
• API consumers should be able to find out about upcoming or existing deprecation
  • Deprecation refers to an API being still functional, but not recommended to use anymore
• Additional resources:
  • Blog article: API Lifecycle Management: Deprecation and Sunsetting [https://apifriends.com/api-management/api-lifecycle-management-deprecation-and-sunsetting/]
  • YouTube video: API Lifecycle Management: Deprecation and Sunsetting [https://www.youtube.com/watch?v=twfufQn1mD0]

(6) Deprecation Model

• A deprecated API is still operational but should be treated with caution
• Deprecation is signaled with a simple HTTP header field
  • Deprecation: Sun, 11 Nov 2018 23:59:59 GMT
• Deprecation scoping is up for the API to decide
  • Header field can show up everywhere or just on specific resources
  • Deprecation can affect the entire API or specific aspects of it
• Additional information can be made available via deprecation links
  • There is not defined format for this resource (it's probably developer documentation)

(7) Deprecation: History

• First version: February 2019
• Published versions: 4
• History & collaboration
  • Datatracker: draft-dalal-deprecation-header [https://datatracker.ietf.org/doc/draft-dalal-deprecation-header]
  • Repo: github.com/sdatspun2/deprecation-header [https://github.com/sdatspun2/deprecation-header]
  • Issues: github.com/sdatspun2/deprecation-header/issues [https://github.com/sdatspun2/deprecation-header/issues]

(9) Linkset: Motivation

I-D: draft-wilde-linkset [https://datatracker.ietf.org/doc/draft-wilde-linkset]

Co-author: Herbert Van de Sompel

• Web Linking [https://tools.ietf.org/html/rfc8288] only defines an HTTP header field but no media types
• Various scenarios call for solutions where links are treated as resources
  • Large sets of links can be hard to embed in HTTP header fields
  • Some scenarios call for links being supplied by a third party
• Define media types that allow sets of links to become standalone resources

(10) Linkset Model

• Web Linking [https://tools.ietf.org/html/rfc8288] defines a model and a serialization for web links
• application/linkset is registered as a media type for RFC 8288 syntax
• application/linkset+json is defined and registered as a JSON syntax for web links
  • The JSON design makes it easy to apply JSON-LD context definitions
• Linksets as standalone resources require careful handling of the context
  • Context is implicit for RFC 8288 scenarios
  • Context must be captured for linksets as resources scenarios
• Resources can link to links pertaining to them using the linkset link relation

(11) Linkset Example

{ "linkset": [
  {
    "anchor": "http://example.net/bar",
    "next": [
      {"href": "http://example.com/foo1"}
      ]
  },
  {
    "anchor": "http://example.net/boo",
    "http://example.com/relations/baz": [
      {"href": "http://example.com/foo2"}
      ]
  }
]}

(12) Linkset: History

• First version: December 2016
• Published versions: 11
• History & collaboration
  • Datatracker: draft-wilde-linkset [https://datatracker.ietf.org/doc/draft-wilde-linkset]
  • Repo: github.com/dret/I-D/tree/master/linkset [https://github.com/dret/I-D/tree/master/linkset]
  • Issues: github.com/dret/I-D/labels/linkset/issues [https://github.com/dret/I-D/labels/linkset/issues]

(14) Warning: Motivation

I-D: draft-cedik-http-warning [https://datatracker.ietf.org/doc/draft-cedik-http-warning]

Co-author: André Cedik

• Problem Details for HTTP APIs [https://tools.ietf.org/html/rfc7807] only cover error scenarios
• Provide a pattern how warnings can be communicated in HTTP APIs
• Provide a JSON structure that APIs can use to represent embedded warnings
• Additional resources:
  • ASC 2020 presentation on YouTube: Communicating Warning Information in HTTP APIs [https://www.youtube.com/watch?v=fdELvQt_Yvw]

(15) Content Warning Model

• Content warning are safe to ignore but may be relevant for users
• APIs can signal that the content contains warning information
  • Content-Warning: "embedded-warning"; 1590190500
• There is reusable JSON structure (resembling the structure of RFC 7807 [https://tools.ietf.org/html/rfc7807])
  • Clients may choose to reuse this structure but are free to do something else
• An IANA registry is established for being able to register other kinds of content warnings
  • The only initial entry is the embedded-warning content warning type

(16) Content Warning Model

• Content warning are safe to ignore but may be relevant for users
• APIs can signal that the content contains warning information
  • Content-Warning: "embedded-warning"; 1590190500
• There is reusable JSON structure (resembling the structure of RFC 7807 [https://tools.ietf.org/html/rfc7807])
  • Clients may choose to reuse this structure but are free to do something else
• An IANA registry is established for being able to register other kinds of content warnings
  • The only initial entry is the embedded-warning content warning type

(17) Content Warning Example

POST /example HTTP/1.1
Host: example.com
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json
Content-Warning: "embedded-warning"; 1590190500

{
  "request_id": "2326b087-d64e-43bd-a557-42171155084f",
  "warnings": [
    {
      "detail": "Street name was too long. It has been shortened ...",
      "instance": "https://example.com/shipments/3a186c51/msgs/c94d",
      "status": "200",
      "title": "Street name too long. It has been shortened.",
      "type": "https://example.com/errors/shortened_entry"
    },
    {
      "detail": "City for this zipcode unknown. Code for shipment ...",
      "instance": "https://example.com/shipments/3a186c51/msgs/5927",
      "status": "200",
      "title": "City for zipcode unknown.",
      "type": "https://example.com/errors/city_unknown"
    }
  ],
  "id": "3a186c51d4281acb",
  "carrier_tracking_no": "84168117830018",
  "tracking_url": "http://example.com/3a186c51d",
  "label_url": "http://example.com/shipping_label_3a186c51d.pdf",
  "price": 3.4
}

(18) Warning: History

• First version: November 2019
• Published versions: 3
• History & collaboration
  • Datatracker: draft-cedik-http-warning [https://datatracker.ietf.org/doc/draft-cedik-http-warning]
  • Repo: github.com/dret/I-D/tree/master/http-warning [https://github.com/dret/I-D/tree/master/http-warning]
  • Issues: github.com/dret/I-D/labels/http-warning [https://github.com/dret/I-D/labels/http-warning]

(20) Overview

• API Deprecation [API Deprecation (1)]: draft-dalal-deprecation-header [https://datatracker.ietf.org/doc/draft-dalal-deprecation-header]
  • Repo: github.com/sdatspun2/deprecation-header [https://github.com/sdatspun2/deprecation-header]
  • Issues: github.com/sdatspun2/deprecation-header/issues [https://github.com/sdatspun2/deprecation-header/issues]
• Linkset [Linkset (1)]: draft-wilde-linkset [https://datatracker.ietf.org/doc/draft-wilde-linkset]
  • Repo: github.com/dret/I-D/tree/master/linkset [https://github.com/dret/I-D/tree/master/linkset]
  • Issues: github.com/dret/I-D/labels/linkset [https://github.com/dret/I-D/labels/linkset]
• Content Warning [Content Warning (1)]: draft-cedik-http-warning [https://datatracker.ietf.org/doc/draft-cedik-http-warning]
  • Repo: github.com/dret/I-D/tree/master/http-warning [https://github.com/dret/I-D/tree/master/http-warning]
  • Issues: github.com/dret/I-D/labels/http-warning [https://github.com/dret/I-D/labels/http-warning]

(21) Thank You!

• Slides online: dret.net/lectures/ietf-109 [http://dret.net/lectures/ietf-109]
• More information about myself:
  • Twitter: @dret [http://twitter.com/dret]
  • youtube.com/ErikWilde [https://www.youtube.com/ErikWilde]
  • linkedin.com/in/netdret [http://www.linkedin.com/in/netdret]