Link usage hints #296
Comments
|
Deferring the exact contents of |
It occurred to me recently that we could introduce Same goes for |
|
@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.) |
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:
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 |
Yes, that's also exactly the mechanism I had in mind for anything that would want to determine sensible values for |
|
I just discovered the Home Documents for HTTP APIs Internet draft which specifies resource hints pretty thoroughly already.
Might be a source of inspiration. |
|
@dlax see mnot/I-D#211 |
|
Having the capability to use both a Of course, 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 |
|
@tbehrsin If you haven't already, please look at the Hyper-Schema Draft-06 migration FAQ for how and why 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. |
|
@tbehrsin as far as shorthand for |
|
OK, I've taken a look at where JSON Home has gone since the last time I checked in (paging @dlax).
The scope of what is included is:
This seems like a good scope definition for us as well. It stays within the single target resource, rather than assembling multiple resources into a larger structure such as an API. Like JSON Home, we should allow some flexibility to cover notable gaps in existing specifications. This covers two use cases:
For the first case, we are well aligned. For the second case, JSON Home is more or less faking response headers for features that have no such headers defined. However, we have a much better mechanism for describing acceptable input, which is a validation schema. At Cloudflare, we actually do this already, although we only make light use of it (for specifying the auth header requirements, mostly). I'm planning to do more with it in the next iteration, though. The obvious benefit of using a schema is that it's consistent with all other data input mechanisms ( So I think we're close to a proposal |
|
I'm uncertain how to name these things. I'm going to call them
TODO: Use names as is, lowercase, or camelCase? "Accept-Patch", "accept-patch", or "acceptPatch"? TODO: Define mapping from HTTP header grammar into JSON and back (this perhaps does not need to be in the spec itself? Would it be a mini JSON Schema vocabulary, or would it just be some sort of appendix / web site guide?) I would also like to have at least one other good example besides HTTP and CoAP. |
|
It turns out that there is a draft proposal for JSON serialization of HTTP headers, so with the usual caveats about referencing other drafts, this provides work we can piggy-back off of, as well as validation that we are not the only people thinking of this sort of thing. Even if our use case is different. Thanks to @dret for pointing this out! |
|
On 2017-08-30 15:02, Henry Andrews wrote:
It turns out that there is a draft proposal for JSON serialization of
HTTP headers <https://tools.ietf.org/html/draft-reschke-http-jfv-06>, so
with the usual caveats about referencing other drafts, this provides
work we can piggy-back off of, as well as validation that we are not the
only people thinking of this sort of thing. Even if our use case is
different.
i think the canonical use case here is that you have some sort of HTTP
log, and want to provide some sort of analysis or BI on top that.
instead of requiring everybody to understand the intricacies of HTTP
header encoding, it would be much simpler for most scenarios to have a
JSON model for this kind of data.
|
Definitely. I need to read the draft in detail, but a JSON model would not only make it unambiguous for us to convey header values (for the purposes of hinting) in a JSON environment, but would then make it very natural to write schemas declaring which headers are particularly important, and what value(s) they might take. That would be a lot harder to do if it were not clear how to express certain headers in JSON, much less in schemas. |
This addresses the request half of json-schema-org#296, and is a companion keyword to "targetHints" (json-schema-org#383). Like "targetHints", this is a rough first pass to get the discussion of specifics started. I expect it to be somewhat underspecified to encourage experimentation. I intentionally chose an example that is both very complex and very useful. It might also be worth putting up a simpler example. Although when this appears right after "targetHints", the simpler header value examples in that section will help motivate what is going on here.
This addresses the request half of json-schema-org#296, and is a companion keyword to "targetHints" (json-schema-org#383). Like "targetHints", this is a rough first pass to get the discussion of specifics started. I expect it to be somewhat underspecified to encourage experimentation. I intentionally chose an example that is both very complex and very useful. It might also be worth putting up a simpler example. Although when this appears right after "targetHints", the simpler header value examples in that section will help motivate what is going on here.
This addresses the request half of json-schema-org#296, and is a companion keyword to "targetHints" (json-schema-org#383). Like "targetHints", this is a rough first pass to get the discussion of specifics started. I expect it to be somewhat underspecified to encourage experimentation. I intentionally chose an example that is both very complex and very useful. It might also be worth putting up a simpler example. Although when this appears right after "targetHints", the simpler header value examples in that section will help motivate what is going on here.
This addresses the request half of json-schema-org#296, and is a companion keyword to "targetHints" (json-schema-org#383). Like "targetHints", this is a rough first pass to get the discussion of specifics started. I expect it to be somewhat underspecified to encourage experimentation. I intentionally chose an example that is both very complex and very useful. It might also be worth putting up a simpler example. Although when this appears right after "targetHints", the simpler header value examples in that section will help motivate what is going on here.
This addresses the request half of json-schema-org#296, and is a companion keyword to "targetHints" (json-schema-org#383). Like "targetHints", this is a rough first pass to get the discussion of specifics started. I expect it to be somewhat underspecified to encourage experimentation. I intentionally chose an example that is both very complex and very useful. It might also be worth putting up a simpler example. Although when this appears right after "targetHints", the simpler header value examples in that section will help motivate what is going on here.
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:
"Accept-Patch"and not a JSON-ized"acceptPatch"So if we wanted to hint at the following authentication header (example taken directly from RFC 7235)
along with hinting at available HTTP methods (example taken directly from RFC 7231)
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" } } } }The text was updated successfully, but these errors were encountered: