Feedback on "Hypermedia and APIs"

[jdesrosiers]

@handrews Great start! I have a few comments.

"API descriptions and operations"

In this section, I don't think what you are calling API descriptions is the important difference between hypermedia systems and something like OpenAPI or RAML. (Correct me if I am wrong that describing the difference is the point of this section). The significant difference is that in a hypermedia system, the resource defines itself as opposed to having to refer to another document that is assumed to be in context. Hydra doesn't belong in the same list as OpenAPI and RAML in any sense. Hydra is very much a hypermedia system.

a Hyper-Schema document, or set of documents connected by "$ref"s, can be assembled to correspond to an API's set of resource sets

I don't agree. In a hypermedia system you can never know for sure anything beyond the capabilities of the resource you have. You can never know an API's complete set of resource sets. Technically, you could crawl all the targetSchemas, but because targetSchema is non-authoritative, so is your set. Although I see why you might find that useful regardless of the uncertainty, I think this statement is likely to mislead readers about how the nature of hypermedia.

[Anthropic]

For anyone not aware this is in reference to Hypermedia and APIs wiki page.

[handrews]

@jdesrosiers thanks for the feedback!

I don't think what you are calling API descriptions is the important difference between hypermedia systems and something like OpenAPI or RAML.

The important difference that I want to talk about is:

• resource/link-orientation vs endpoint/operation-orientation
• open-ended independent resource representations vs closed API scope

I don't, in this article, care whether that's the defining distinction of hypermedia. Whatever it is, it's the distinction that I've found actually useful to talk about. It's a very easy distinction to describe once you work out the right terms, and it addresses the primary confusion that I had in #94 and #95, which I have seen reflected in many other places (not limited to this project).

Perhaps there is another name for it? It's definitely the topic I intend to cover.

The significant difference is that in a hypermedia system, the resource defines itself as opposed to having to refer to another document that is assumed to be in context.

I suspect your phrasing is not coming across quite right, because that sounds like JSON and JSON Hyper-Schema don't qualify, as you need multiple documents to use the as hypermedia.

I'm specifically avoiding the typical language around hypermedia and "out of band information" or whatever because if anything is clear from the last two decades of conversation on the topic it's that that approach is not effective as education. There are plenty of articles and/or rants from Fielding about that, there's no need for me to write another one.

Hydra doesn't belong in the same list as OpenAPI and RAML in any sense. Hydra is very much a hypermedia system.

Hydra's a weird one. I included it because it has an ApiDocumentation object (sets the scope to be an API, although not all defined statically), and most importantly, it defines operations (it even calls them that) in terms of HTTP methods, requests, and responses. That is exactly the definition I am using.

But it is weird because it's also hypermedia, even if I don't much care for it (which is a shame because I like JSON-LD), so it's better to take it out to be less confusing. Maybe worth a note at the end because it's a good illustration that the two concepts are not mutually exclusive.

a Hyper-Schema document, or set of documents connected by "$ref"s, can be assembled to correspond to an API's set of resource sets

I don't agree. In a hypermedia system you can never know for sure anything beyond the capabilities of the resource you have

Two responses to this part:

1. I said can be, not "it totally makes sense and you should do it." :-)
2. I said "a set of Hyper-Schema documents", not "a hypermedia system", and I did so very intentionally

The point of that paragraph is to acknowledge that yes, you can hammer Hyper-Schema into something that looks like an API description format if you really want to, but that's not what it is. Why did I do that? To prevent someone from plopping down a hyper-schema of their entire API in a static view and arguing with me about it. Because I have seen a lot of hyper-schemas done that way.

I think this statement is likely to mislead readers about how the nature of hypermedia.

It definitely needs clarification, and your response has been very helpful, thanks!

[handrews]

@jdesrosiers

• Removed any mention of Hydra
• Added some wording around a composite Hyper-Schema document appearing somewhat like an API description format to make it clear that it is not such a thing
• Added some discussion of what an open-ended hypermedia API might be like, although it's probably not a very good discussion yet

[handrews]

@jdesrosiers

Also added a 2nd intro paragraph explaining the focus of this article not being to review hypermedia fundamentals, but to consider using JSON Hyper-Schema as hypermedia and how that relates to other JSON API technologies. Please let me know if this makes it more clear and easier to understand the article. It's definitely important to set up the discussion context and I was not doing that well.

[jdesrosiers]

I don't, in this article, care whether that's the defining distinction of hypermedia.

Fair enough. But, I think the article needs to explain why this is an important distinction.

The significant difference is that in a hypermedia system, the resource defines itself as opposed to having to refer to another document that is assumed to be in context.

I suspect your phrasing is not coming across quite right, because that sounds like JSON and JSON Hyper-Schema don't qualify, as you need multiple documents to use the as hypermedia.

I know this is confusing, but I assumed you would know what I meant because we have had this discussion before. The important word here is "assumed". In Hyper-Schema, that association is explicit and controlled by the resource, not some other authority. It is no more an issue to have multiple documents as it is for a web page to reference stylesheets as long as it is the web page that defines those relationships.

Added some wording around a composite Hyper-Schema document appearing somewhat like an API description format to make it clear that it is not such a thing

That's better. I think it's just the sentence structure, but I still think this could be misinterpreted. Adding some explanation about why it is not the same thing would help.

[handrews]

Fair enough. But, I think the article needs to explain why this is an important distinction.

Definitely, I think I was adding a first attempt while you were writing that comment!

I know this is confusing, but I assumed you would know what I meant because we have had this discussion before.

I seem to have lost track, my apologies :-/

There are ways to connect at least some types of API description formats directly. If not built in to the formats themselves, by using relations such as "describedby" that are generic enough for their meaning to be driven by the target media type.

I'll try to think of how to express this better, thanks for the continuing responses this is all very helpful!

That's better. I think it's just the sentence structure, but I still think this could be misinterpreted. Adding some explanation about why it is not the same thing would help.

Yeah, that's reasonable I'll keep working on it.

[jdesrosiers]

@handrews Other discussions led me to more questions about API description and I thought this was a more appropriate place to discuss them.

You have said that a hypermedia media type should focus on resources and relations rather than operations and endpoints. It seems to me that HTML Forms are a way of describing operations. I may still not completely understand what you mean by "operations". Considering that HTML is the most successful hypermedia media type ever, can you explain how it fits the principle of resources and relations over operations and endpoints?

[handrews]

Considering that HTML is the most successful hypermedia media type ever, can you explain how it fits the principle of resources and relations over operations and endpoints?

Because it is for humans, and it is 24 years old. The use case is radically different and I still don't understand why you think it translates at all.

• We now have a generic concept of what a link is and how it can be serialized
• Since all real semantics were deferred to natural language text, there were no possible non-mechanism semantics that could be used in HTML, which is why HTML never developed such concepts

The division of labor in HTML is:

• content author provides semantic cues in natural language; end user decides whether to use them
• developer provides mechanisms; browser knows how to execute them

The division of labor for an API is:

• developer provides semantic cues in relation types, with mechanisms following from meaning
• generic client can learn semantics (and the implied operations) that are appropriately generic, without requiring an update to the media type specification
• generic client can learn generic operation mappings per URI scheme, so there is no need to preempt link relation types for mechanisms
• applications make use of domain-specific semantic cues, and their implied operations; the uniform interface ensures that direct operation cues are not needed

[handrews]

I mean, Perl was incredibly successful but we don't make every scripting language since then model itself after Perl. And the use case divergence between HTML and Hyper-Schema is far larger than Perl vs Python or Ruby.

[handrews]

I'm going to revamp the whole thing after draft-07 goes out. I feel like my concept of what JSON Hyper-Schema is and isn't has become more well-defined. So I'm not going to worry about further tweaking the wording of this version. I may do the next version as a more formal document on the web site and we should definitely hammer on that until it is very accessible to newcomers.

As for the HTML arguments, they've played out over numerous issues, in more detail and in more concrete contexts than this, and I feel like the term "dead horse" is appropriate :-/ So I'm going to close this out.

[zdne]

@handrews

I feel like my concept of what JSON Hyper-Schema is and isn't has become more well-defined. So I'm not going to worry about further tweaking the wording of this version

Did you publish anything on this matter yet? I'd be curious to hear more! Thanks!