Relationship to JSON Home?

[handrews]

See also mnot/I-D#201

JSON Home seems to complement each other nicely, with JSON Home offering solutions for problems that would require substantial additions to JSON Hyper-Schema to fully address ( #88 , #89 ).

Should we try to align syntaxes as much as possible? In particular, there is overlap between #52 (extended templating) and the URI Template aspects of JSON Home.

Just to be clear, JSON Hyper-Schema should not do anything specific to JSON Home, nor vice versa, but a consistent approach would make using them together more enjoyable.

[awwright]

There's a ton of hypermedia formats out there, and many that are more mature.

The most interesting part of that is the proposed resource hints registry, I'd focus on that.

[handrews]

There's a ton of hypermedia formats out there, and many that are more mature.

The ones I can think of offhand have various shortcomings for use with Hyper-Schema:

• JSON-LD, HAL, and Collection+JSON do not have anything like hints
• SIREN and HYDRA do describe operations, but overlap too much with Hyper-Schema using different approaches

Am I missing any major JSON-based hypermedia format?

What I like about JSON Home is that it does a minimal set of things. It just defines a home document, without constraining any other part of the API. Its approach is more compatible with Hyper-Schema than anything else. JSON Home leaves a lot to the media type(s) used by the rest of the API, and its approach to URI templating is very similar to ours (I'll elaborate on this in another comment if there's enough interest to discuss it).

If Hyper-Schema wants to define operations using the same sort of hints approach as JSON Home, then I would not need JSON Home. However I had gotten the impression that you are very much against that level of specifying operations (naming protocol-specific methods, for instance). Could you please clarify your position on this? I don't want to agitate for any sort of alignment if JSON Hyper-Schema is going to encompass this functionality.

[awwright]

JSON Home defines them as exactly what it sounds like: Hints for things to try first, but not necessarily a comprehensive list of what the server supports. Perhaps one could take it to mean that.

For a comprehensive listing of the exact methods and things that a server supports, maybe you're looking for WSDL? (idk, maybe it only describes SOAP and not HTTP more generically)

There also seems to be WADL

[handrews]

For a comprehensive listing of the exact methods and things that a server supports, maybe you're looking for WSDL? (idk, maybe it only describes SOAP and not HTTP more generically)

There also seems to be WADL

Ugh, no! No, no, no, no, no! :-P That stuff is for generating tons of documentation that no one reads. Except for people who then use it to tightly couple their client and server which is totally against the point of REST. WADL is better than WSDL but again duplicates a lot of what JSON Schema is doing. And in XML. Ugh. Need to scrub brain out with bleach now ;-)

All I need is an enumeration of resources and hints as to what they can do, primarily to indicate what's reasonable to try without issuing a non-cacheable OPTIONS request every time I encounter a resource. My objections to relying entirely on HTTP at runtime are basically:

• OPTIONS is not cacheable, and is often not implemented (relevant for legacy systems that can't be easily changed- for new systems, I'd just implement OPTIONS)
• HEAD is cacheable and might be a viable alternative, although I feel like that's not quite right?

To be honest I've been too busy trying to keep up with these conversations to re-read the spec on HEAD and OPTIONS and reason my way through how they should be used beyond "OPTIONS is not cacheable and that's bad."

JSON Home's hints paper over those problems without imposing a contract on the resources at runtime. Depending on how much documentation I need to generate, those hints also let me express whether a resource is readable/writeable/deletable/etc. I would rather not generate that much documentation but Engineering does not always drive customer-facing requirements in the commercial world :-)

From my perspective, JSON Home takes several key elements of the Riverbed service definition approach that I worked on before (explicit enumeration of resources and identification of operations) and packages them up in a way that is more RFC-compliant and focused than the way Riverbed service defs glommed them together with JSON Schema. JSON Home scrupulously avoids duplicating the role of media types beyond this one home document, which is again what I want because JSON with JSON Hyper-Schema does all of the stuff I need there.

If this sound different from things I've been saying before, it's because all of these discussions here have helped me clarify my various API goals immensely. Although to be clear, I've never wanted to go anywhere near something like WSDL or WADL. The docs produced by the Riverbed service definition are too much documentation for REST from my perspective.

[handrews]

Now I see issue #73 about adding an allow to the LDO, so I guess you are not against noting HTTP methods as hints. Sorry, that one slipped by me in the flood of activity over the last few days.

If both we and JSON Home are doing URI templating and operational hints, it would be great to use the same format as much as possible. Enumerating the resource classes in an API is still, as I understand it, out of scope for Hyper-Schema, so I would still want JSON Home (or something) that would perform that enumeration.

[handrews]

I don't see anything actionable for this that's attracted enough interest to keep open. I don't think we need this open just to remind us to look at how JSON Home does hints.