HTTP Link Hints

[mnot]

The high level idea is that links (as per RFC8288) often need to give hints about how to interact with the resources that they point to. HTTP has several ways to discover this as you interact with them (e.g., the Allow header for methods, Accept for formats, and so forth), but not any way to write that down separately.

HTTP Link Hints aims to fill that gap, by specifying a set of link target attributes that describe how to interact with the resource with HTTP. A couple of important points to note:

• These are just for HTTP interactions; they don't cover other aspects of a resource or its behaviour
• They are hints; they can and will be overridden by the actual runtime behaviour of the resource, and the client needs to keep that in mind
• Because target attributes are defined by link relation types and/or link serialisations (see RFC8288 s 2.2), HTTP link hints need to be 'opted into' by one of them; they are not universal.

See the Internet-Draft proposal for details.

[darrelmiller]

I'm seeing a lot of similarity here with what OpenAPI descriptions provide.
Instead of this:

{
  "_links": {
    "self": {
      "href": "/orders/523",
       "hints": {
        "allow": ["GET", "POST"],
        "accept-post": {
          "application/example+json":
            {}
        }
      }
    }
  }
}

it would look like

{
  "_links": {
    "self": {
      "href": "/orders/523",
       "hints": {
         "get": {},
         "post": {
               "requestBody": {
                    "content" : {
                               "application/example+json" : {}
                          }
                  }
            }
      }
    }
  }
}

For sure the OpenAPI is bigger and uglier, but it also supports a lot more capabilities than are currently described in the draft. If we go down the path of defining additional hints over time, how long before we have two ugly things that are inconsistent.

When you use the constraint "just for HTTP interactions", is that saying that any attempt to describe the shape of the payload would be avoided? That would be a clean distinction. However, the pressure I have seen before to describe "forms" suggests to me that hints for payload shape would soon be in demand.

[thexa4]

It would be pretty cool to have a standardized links for this, I didn't know this draft existed and solved it with a media-type that's available everywhere.

An example of it can be found here: https://wondrmedical.net/api/login?api_viewer=application/vnd.delftsolutions.endpoint_description.v1+json