Link usage hints

[handrews]

JSON Hyper-Schema should not include keywords that come from specific protocols, and certainly not ones that do not generalize well enough to apply to any protocol.

This would suggest that "allow" as proposed by #73 would not be ideal as it is HTTP-specific, although the concept generalizes well, so it's not an unreasonable proposal either.

However, there are several things such as HTTP's "Allow", which would optimize and document how to use the protocol to interact with a link target, as opposed to the current LDO hints such as "mediaType" which describe the target resource itself, independent of how it is accessed.

A more clear example is the "Accept-Patch" header, which is critical for correctly constructing an HTTP PATCH request (in conjunction with either "targetSchema" or the schema linked in the response to a HEAD or GET to the target). "Accept-Patch" is very specific to HTTP (or, really, an extension to HTTP). No current Hyper-Schema keyword could accommodate it, and adding an "acceptPatch" field to the LDO would be inappropriately specific.

---

One approach would be a "usageHints" field for hinting at protocol usage meta-data that could otherwise be discovered by interacting with the target resource. This field would not encompass meta-data that describes the target resource independent of protocol.

The value of this keyword would be an object. The exact possible values for the contents of the object are deferred to the protocol and the target resource, but Hyper-Schema would define general rules to provide for interoperability.

Here's a strawman proposal:

• keys would be the meta-data field names in whatever form is deemed canonical by the relevant standards, e.g. "Accept-Patch" and not a JSON-ized "acceptPatch"
• values would be as they would exist in the protocol, except that lists and named fields SHOULD be structured using JSON arrays and objects

So if we wanted to hint at the following authentication header (example taken directly from RFC 7235)

WWW-Authenticate: Newauth realm="apps", type=1,
                       title="Login to \\"apps\\"", Basic realm="simple"

along with hinting at available HTTP methods (example taken directly from RFC 7231)

Allow: GET, HEAD, PUT

the result would look like:

becomes:

{
    "rel": "self",
    "href": "/foos/{id}",
    "usageHints": {
        "Allow": ["GET", "HEAD", "PUT"],
        "WWW-Authenticate": {
            "Newauth": {
                "realm": "apps",
                "type": 1,
                "title": "Login to \"apps\""
            },
            "Basic": {
                "realm": "simple"
            }
        }
    }
}

[handrews]

Deferring the exact contents of "usageHints" to the protocol + resource also allows resources to define their own meta-data extensions, for instance the "X-*" HTTP headers that are common mechanisms in APIs.

[jdesrosiers]

This would suggest that "allow" as proposed by #73 would not be ideal as it is HTTP-specific

It occurred to me recently that we could introduce allow in a way that is not HTTP-specific. The href scheme determines the protocol that is used and the protocol determines what values allow can have. Different protocols means different possible values. Therefore, the spec doesn't have to be HTTP specific, it can just defer to the protocol specified in the href.

Same goes for usageHints. You can directly use HTTP headers without the spec necessarily being coupled to HTTP.

[jdesrosiers]

@handrews This proposal seems like that API description stuff you have been saying doesn't belong in Hyper-Schema. Can you explain why this proposal is not API description?

(I realize this question sounds passive aggressive. Please don't take it as such. I'm still trying to figure out exactly what you mean by API description.)

[handrews]

I realize this question sounds passive aggressive. Please don't take it as such.

Given how often I get my tone wrong in these sorts of conversations, I am in no place to throw stones!

And I think it's a fair question anyway, and the answer may even end up being "actually it doesn't belong here", but I'll explain why I went ahead and filed it. When I talk about aspects of API description being undesirable in JSON Hyper-Schema as a media type, I am making the following distinctions:

• representations & links vs endpoints & operations
• single representation scope vs API scope

The usage hints work with links rather than operations, meaning that those hints do not need to be changed for different HTTP methods. Yes, some of them ("Accept-Patch" being a particularly obvious one) are only useful with certain operations that can be performed with the link, but we don't need to change them for each operation. They are always the same hints, which may or may not be relevant depending on the operation being performed.

They are also single representation scoped rather than API scoped. With the auth info, this usage hint is saying exactly what the header would say in a HEAD response. It is relevant to the target resource resource as accessed from the context representation. It doesn't say anything one way or the other about auth across an entire API.

I'm not sure I'd want to do auth this way, but it was an interesting example with some complex structure.

Another point is that a mechanism like "usageHints" that defers its exact contents to the protocol will be relatively easy to misuse, but that is better than coupling HTTP and Hyper-Schema. Ultimately, an implementation can completely ignore hints and still be compliant, because they are non-authoritative. It would be a rather lame implementation, but technically correct.

[handrews]

The href scheme determines the protocol that is used and the protocol determines what values allow can have. Different protocols means different possible values. Therefore, the spec doesn't have to be HTTP specific, it can just defer to the protocol specified in the href.

Yes, that's also exactly the mechanism I had in mind for anything that would want to determine sensible values for "usageHints". The spec for "usageHints" needn't mention HTTP at all, although as usual some HTTP-based examples are generally helpful.

[dlax]

I just discovered the Home Documents for HTTP APIs Internet draft which specifies resource hints pretty thoroughly already.
Quoting introduction of Section 5 of the draft:

Resource hints allow clients to find relevant information about
interacting with a resource beforehand, as a means of optimizing
communications, as well as advertising available behaviors (e.g., to
aid in laying out a user interface for consuming the API).
Hints are just that - they are not a "contract", and are to only be
taken as advisory. The runtime behavior of the resource always
overrides hinted information.

Might be a source of inspiration.

[handrews]

@dlax see mnot/I-D#211

[timoshisa]

Having the capability to use both a "hints" LDO keyword in addition to short-forms "allow" and "method" for HTTP-like protocols would be beneficial. For a vast majority of cases JSON Hyper-Schemas will be used for HTTP API description and validation (client and server). With this end in mind it would be good to try to keep things simple for those users, and being able to specify a method directly inside the LDO rather than as part of a "hints" section would be important for both accessibility of the standard and also ease-of-use generally. There are other line-based internet protocols like SIP which share the same semantics. One can also envisage (and I have used in the past) WebSocket based protocols utilising method/path tuples in JSON documents.

Of course, method, allow and hints should be wrapped in a oneOf to prevent confusion over which one should be used.

The previous draft with "method" is in use by several software projects already. Granted this is still a draft spec, but it is functionally a very important feature of the spec that needs to be put back into the draft sooner rather than later. Specifying with "rel" seems to be too vague (please correct me if I am wrong, would be useful to have something more formal in Hyper Schema's docs as a formal mapping for HTTP is not easy to find.) Without the ability to specify HTTP method we are only able to specify the protocol without being able to fully express the address of how to reach the endpoint (in HTTP, href is only one of the fields needed.)

In terms of HTTP-agnosticism, "method" and "allow" don't need to be locked down to defined-at-this-time HTTP methods and can have their interpretation left open to the protocol being targeted. There is little need to validate the keywords in this spec, and validation can be deferred to protocol-specific schemas.

On a side-note: I favour json-home's camel-cased properties, simply for consistency with the JSON Schema specification and current vogue for JSON document design. Certainly it's cosmetic, but the resulting hypermedia documents will look much cleaner and also it brings consistency with json-home. I also prefer either "usage" or "hints" instead of "usageHints", again for cosmetics.

[handrews]

@tbehrsin If you haven't already, please look at the Hyper-Schema Draft-06 migration FAQ for how and why "rel" is not too vague in many cases. If you are following HTTP semantics in terms of methods and representations, you do not need to re-specify links for each method. For dealing with non-HTTP-semantics-complying APIs, see #226.

Regarding camelCase, it depends on whether we want to say "the keys are whatever the specific protocol uses", in which case we do not get to determine the formatting, or whether we want to define a mapping from arbitrary protocol syntax into camelCase. I could go either way, but I tend to prefer minimizing parsing / translation so simply saying "it's whatever the protocol expects" is the option that produces the least amount of work for implementations.

[handrews]

@tbehrsin as far as shorthand for "allow" or anything else, let's keep that discussion in #73 so this issue stays focused on the generic mechanism. That is a complex topic and one that is not impacted by whether we add specific keywords (if anything, it would be the other way around).