clarify documentation formats

[fosrias]

@smizell I think this is warranted and really makes this solid.

[fosrias]

@smizell Comment addressed.

[fosrias]

Leaving it to you to merge, BTW.

[smizell]

Ok, so I'm having some conflicting thoughts on the recommendation to add a link to the docs in each response. This is broader than this PR of course, but I want to bring it up since it's in context here.

I know I initially was for this, and last night was for your PR here, but I spent some time thinking about the problem this solves in this context, and I'm not sure I coming up with anything specific. Please hear out my thoughts here :) In summary, I think we should not include recommendations around linking to documentation in responses.

One interesting thing was, I read through the spec and noticed that all guidelines are about links—how to include them, what to document, and how clients should use them. Our recommendation and example for linking to the docs feels a little too narrow in light of all of the other guidelines.

As I thought through this, I considered the scenarios where linking to documentation might be helpful. For domain-specific clients, this isn't needed. The client will be built from the specification, so the client builder will know the documentation. I also think it's going to be rare that someone just happens upon one of these APIs without knowing any context or how to find API documentation. Even if this scenario presents itself, including a link to docs just in case seems like prematurely optimizing.

It then appears that content negotiation is for general clients trying to discover the documentation for the API. This also seems uncommon for the persona I have in mind for this pattern. Taking this into account, it then feels like bloat to recommend that the URL to the documentation be in every response. It made me wonder if it would be better to simply put a link to the documentation in the home of the API or add a link in the OPTIONS method for each resource if it's really needed for the link to be available at runtime.

Simplifying this all would be to only recommend to have documentation and make it discoverable in some way, which I feel is implied with various guidelines. I think our recommendation to include a link and support content negotiation around API description documents is too constrained and out of scope of this document. I think people should encounter the RESTful JSON design pattern and only get ideas on adding links into their responses.

This may, however, be a broader API pattern we can dive into with a well-defined problem space. It comes under the topic of "how does an API provider make their API discoverable?"

Thoughts? Sorry to jump around on this.

[fosrias]

Ha. Ok so here is the one thing I think we must address, that documentation is in-band. Now that term mean nothing to J.Q. Public, but in principle it must be addressed. I am open to a fuzzier discussion on how to do this, but think we must add something.

Frankly, I think the more elegant way to do this is to conneg on the url of the resource to get the documentation, e.g application/openapi+json/yaml application/vnd.apiblueprint.ast, application/alps+xml, etc. The only problem with that would be conneg on text/html since it is quite likely that the resource has a represenation in HTML. And I am not entirely convinced that do this is right from a representation standpoint. So, back to you on thoughts.

[smizell]

I think it's important to address as well, but my thought is it doesn't fit into this RESTful JSON document. This doc is about adding links, not about a complete solution. I think if we stick with that one idea, it can drive people to think about other ideas. These concepts are not even close to being on the majority's radar.

I also think the content negotiation is just one possible way of moving it in band. There is apis.json that defines information for the API for example.

My gut feeling is to not try to solve it all. Narrowly handle links and see if it catches on.

[fosrias]

Ok. So, what if we just close this PR. Leave everything as it is. I would leave the example as well as it is only an example. I think the current wording is general enough. I suspect the way to give more insight is in RESTful patterns or in sample Swagger/Blueprint docs. If you concur @smizell, go ahead and close this and we will call it good for now.

[smizell]

Yeah, right now we have:

API providers SHOULD reference the documentation in a response.

I think that's ok. I'm good on closing this for now and thinking more on it. Again, not against the thought of this.

I think we should remove the doc link example too. I think without a more thought-out solution it will confuse more than help. We can always add it back down the road, but keep feeling it's not ready to be there.

[fosrias]

@smizell Closing this and will take up discussion on docs_url separately.