hyper-schema: Is generating API documentation a goal?

[handrews]

I've come to the realization that most of the apparent conflicts in issue #48 are because the problems that I'm raising are motivated by documentation generation requirements, while other people's responses have been driven by API execution requirements.

These are very different sets of requirements, so unsurprisingly, the result has been a sprawling mess of confusion despite a great deal of patience exhibited by everyone involved. (Thank you all!)

The introduction to the JSON Schema Core document (on master) states:

JSON Schema is intended to define validation, documentation, hyperlink navigation, and interaction control of JSON data.

The phrase JSON data is key. Does this just mean each individual schema is intended to define documentation itself? Or do we want to facilitate document an API as a larger entity? In either case, what sort of documentation do we want to enable and encourage?

The goal here is NOT to turn JSON Hyper-Schema into API Hyper-Schema. The primary unit of focus should remain individual schemas and instances. But that leaves quite a bit of leeway.

I have a lot more details on this topic, but perhaps it is best to start with the fundamental question.

Note that documenting a fully RESTful API and documenting other HTTP APIs in the typical manner produce different requirements. Depending on what we decide about HTTP-abusing APIs in issue #88 , we may need to consider both.

[handrews]

Mark Nottingham's JSON Home proposal may actually provide all information needed to generate documentation that is not already covered in JSON Schema.

This requires more thought, and I'd be much happier if the URI templating syntax in each were identical, but a system that uses different proposals for describing how to interact with JSON hyper-media vs how to document the capabilities of an entire API would be preferable to burdening JSON Hyper-Schema with a bunch of extra requirements.

[handrews]

@awwright if you want to declare API documentation (as opposed generating documentation of individual schemas) out of scope for JSON Hyper-Schema, I'm fine with closing this. I can file a more specific issue if we find something that really falls between the cracks of Hyper-Schema, JSON Home, and whatever else is available.

We should only keep this open if we want to talk about how to add a notion of "an API" to Hyper-Schem for documentation generation purposes. I don't have any other use cases for adding multi-resource API-awareness to Hyper-Schema.

[jdesrosiers]

I don't think generating documentation should be a goal of JSON Hyper-Schema because it is not a service description language. Nor should it be in the business of a service description. Hyper-Schema is a way of defining hypermedia controls for a JSON document. That's it.

I know we are all weary of HTML analogies at this point, but I think it is apt. Asking if JSON Hyper-Schema should be able to generate documentation is like asking if we should be able to generate documentation for a website using the links and forms on it's pages. It doesn't make sense for two reasons. The first reason is that HTML is not designed for such a task and it is therefore not well suited for it. You would have to crawl the site to get all the information and then compose it in some way to produce documentation.

But all of that is of little concern because of the second reason; websites don't need documentation. They follow standards like HTTP and HTML and are self-documenting with forms for functionality that is specific to their site.

Hyper-Schema is the same way; there should be no documentation necessary beyond the self-documenting parts. A web browser is a generic client that understands URI, HTTP, HTML, etc. Everything in HTML is unambiguous enough that a generic web browser can generate a UI for it.

Hyper-Schema should be the same. There should be generic Hyper-Schema clients that consume Hyper-Schemas the way a web browser consumes HTML. That is exactly what @geraintluff's Jsonary does. When I design APIs, I use Resourceful as a generic server and Jsonary's generic browser as a generic client. I don't do anything with the API that can't be handled by the generic client. Thus my documentation needs are minimal because everything is so formal that it is unnecesary to document anything beyond HTTP and Hyper-Schema which is not my responsibility (as an API designer) to document.

A front-end client should be completely generic for any API. A back-end client should require only matching up the user's data with the data the forms require. Everything else should be able to be handled generically. This bit that has to be customized could be done generically with JSON-LD where the semantics of fields are known programmatically, but with just JSON Schema, we can't have a completely generic back-end client. We should be able to get really close though.

So, I think JSON Hyper-Schema should not be in the business of generating documentation. It should be in the business of making documentation as irrelevant as possible like it is for a website.

[handrews]

@jdesrosiers

We're on the same page about imposing documentation generation requirements on Hyper-Schema (although documentation generation is explicitly given as a use case for JSON Schema). The only reason I have not closed this is to let @awwright make it official.

However:

there should be no documentation necessary beyond the self-documenting parts

You're still thinking in terms of execution. I agree that you should not need any of this extra information to write a generic user agent. I have written generic user agents. They don't need any of this. But humans need to know stuff. The problem is not that HTTP APIs are documented, it's that people document the wrong stuff.

From Fielding:

It is the same basic issue as with human communication: we will always need a common vocabulary to make sense of it. Exposing that vocabulary in the representations makes it easy to learn and be adopted by others. Some of it will be standardized, some of it will be domain-specific, but ultimately the agents will have to be adaptable to new vocabulary.

You need to document the vocabulary. That won't look at all like most HTTP API documentation (which I hate- it bakes in anti-RESTfulness everywhere). You need to document, in a general sense, what is out there.

To quote Fielding again: "REST doesn’t eliminate the need for a clue."

User agents don't care. They don't need to know what they are working with at all. I have never thought that they do. Again, I have written one- the "method" confusion is the only part that came close to violating this, and all it really did was skip over the need for OPTIONS calls and put a band-aid over non-HTTP-compliant APIs.

But ultimately, a human has to use that user-agent to do something, and a human needs to know what concepts are around. They should be using a duck typing approach to data fields and link relations rather than hardcoding expectations based on examining the schemas (this is why documenting exact request/response formats is undesirable, although that's the hardest bit of undesirable documentation to get rid of).

This issue was about whether to document APIs instead of just individual resources. I think we're all in agreement that the answer is no. But it's important to remember that using an API is not the same thing as building a user-agent for arbitrary resources. Using an API is something on top of a generic resource-oriented user-agent, and at some point, some human has to know why they want to do anything with the API at all.

The fact that nearly everyone way over-documents their APIs doesn't mean that humans can understand the API with zero documentation. Even if all of that documentation does is define domain-specific terms and describe how standardized things are used. I would not just tell everyone to go read a bunch of linking RFCs to understand what we do with standardized links, for instance- that's too low-level for most people.

[jdesrosiers]

at some point, some human has to know why they want to do anything with the API at all

Right, but this would be at a pretty high level. Not anything that makes sense to have a service definition language for. I would do that kind of documentation with the formality of a blog post and let the API itself describe the technical details. I think we are on the same page, but maybe to different extremes. For example, I see no value in something like the JSON Home proposal you pointed to.

[handrews]

@jdesrosiers : Yes, for the most part I think we're vehemently agreeing :-)

But I think there are some very interesting points here if you'll humor me for a bit longer.

Right, but this would be at a pretty high level. Not anything that makes sense to have a service definition language for.

Exactly. I hate service definition languages, because they are geared towards producing anti-RESTful documentation (URI templates, HTTP methods, exact request/responses formats, etc.) I don't want any of that (I didn't even much care for it in the Rivebed service definition format, but I didn't have a good alternative worked out at the time).

All the comments that may have looked like me advocating for turning JSON Hyper-Schema into a service definition language were due to me having old documentation requirements mixed into everything else in my head. This whole series of discussions has helped me separate out those requirements, so I no longer want to do any such thing directly in JSON Hyper-Schema.

I would do that kind of documentation with the formality of a blog post and let the API itself describe the technical details.

Try that with a suite of 20 or so APIs with several hundred resource classes and customers ranging from random free sign-ups to major enterprise businesses and let me know how that works out :-)

While I'm being slightly facetious, there's a really important point here that gets overlooked. JSON Hyper-Schema is a means to an end. It is not an end in and of itself. No matter how far your component is from the end user (in our case, end programmer), you always want to keep those end users and their needs in mind. You can guide their needs somewhat, but ultimately you can't control them. For instance, I can get them away from URI template documentation by providing a more pleasant alternative.

However, if my only API documentation was a couple of casual blog posts, the support department would kill me. And I am in a pretty friendly environment when it comes to pushing for REST and moving away from old ways of doing things.

So I am looking for the way to provide the minimum amount of formal documentation possible. But no less.

I see no value in something like the JSON Home proposal you pointed to.

I've got three generations of legacy APIs that predate me joining my current project, ranging from RMM 0 (everything is POST to the same URI with an "action" field and all responses are code 200) up to almost RMM 2 (resources are identified, and there was intent to use the HTTP methods correctly but the execution left a bit to be desired).

JSON Home looks great to me because it can supply, through target hints, information on how those APIs can be used. Attempting to just use hyper-schema and defer the interaction details to relying on HTTP would be somewhere between worthless and disastrous.

With JSON Home, I can write a JSON Hyper-Schema compliant generic user agent, which also understands application/home+json or whatever Nottingham ends up registering (application/json-home is apparently a placeholder). Between the two media types (particularly JSON Home's target hints), I can (probably- error descriptions are a bit questionable) describe the existing behavior and ensure that my generic user-agent can work cleanly with all four generations of API, even though only the next generation will be RESTful.

I hope you can see the value in that, possibly while thanking the stars that you don't have to deal with it yourself! :-D

[jdesrosiers]

I would do that kind of documentation with the formality of a blog post and let the API itself describe the technical details.

Try that with a suite of 20 or so APIs with several hundred resource classes and customers ranging from random free sign-ups to major enterprise businesses and let me know how that works out :-)

OK, a series of blog posts then :-). Actually, the statement comes from experience. The largest API I've designed was an Order Management API for a e-commerce service provider that I was working for. It covered everything from shopping cart to shipping. It wasn't as big as what you worked on, but it was big. We had the type of documentation that you and I both hate (I lost that battle too). The thing is, implementers hate it too. No one used it. All they were interested in was code examples.

You are right, however, that I have approached these discussions from an ideal, greenfield point of view. There is value in making things easier for legacy systems to transition to a more RESTful approach.

[handrews]

The thing is, implementers hate it too. No one used it. All they were interested in was code examples.

Totally agree, and I've been happy to find a lot more agreement on this in more recent work. This is also why I want a generic user-agent (in however many languages), because then we can just document the user-agent and how to use the "vocabulary" of stuff involved (link relations, important data fields which should be named consistent with the link relations, etc.) in a duck typing approach where you never quite know or care what you have as long as it has the things you need.

[awwright]

For the record, the website already has an entire section on "API generation".

And website still can have a "help" section, or tutorials, and things like that. It's just not something that most people consult on a daily basis. Likewise, an API can have tutorials and a support manual.

[handrews]

@awwright perhaps I am just insufficiently caffeinated (it's early morning here), but where exactly is this "API generation" section? I see some stuff under software that is related, but don't see pages on the JSON Schema site? Again, apologies if I'm missing the really obvious.