Documenting Hypermedia API

Conveyor:

Dmitry Pavlov @zeldigas

Attendees:

Mike A., Jorn, David, Ryan, Greg Scott (@gregoryjscott), Tony, Sergey Lyubimov @SergeLyubimov...

Send your tweets to @SergeLyubimov and I'll add you.

Notes

Main concern : most of the documentation has a focus on URI (uri templates) whether it is link to resources or actions (i.e. Swagger, API Blueprint).

Client need to know where to try to knock to, but it's the only url, not for every resource. With hypermedia URI doesn't matter, you need to know only the root endpoint, and than you will discover , browsing through relations from one resource to another or performing actions. So

Concern against docs at all:The role of documentation overall are really reduced in hypermedia, as API supposed to be explorable, so it will be much easier just to go and see, rather than learning docs. No one might learn them.

Questions and answers

But how to avoid URLs?

One of the solution worked (Jorn) is to document the link relations, resources and actions in a plain text (word/html) and tell to clients that those relations are exists somewhere in ecosystem. Thus we avoid using urls (or url templates).

Example of such description:

Resource
   name (class)
   properties
   List of links(in terms of relations)/actions we can expect (but they might not be there)

Link relations
   description of what this link is for. If link is generic 

Actions
   what this action do (the purpose) parameters (or payload description if this is not a like form submission) and response results (status codes etc.)

What is the purpose of having hypermedia documentation?

To give to client an overall idea of the resources and actions without dependence of the current resource state

Why don't send documentation in response to OPTIONS request?

at the moment OPTIONS response body is not defined in RFC, but might be changed in future. Also, HTTP is just a transport, so might not good to stick onto it.

Does it worth to embed all documentation into resource response, or it worth to have just a link to profile?

May be ALPS can do this kind of things?

Not sure, as ALPS looks like allow you to list just vocabulary of all relations (at least it can be) + alps is more machine readable format, and we try to find out solutions for human readable docs too.

As a solution we can embed link in machine readable format to a human readable documentation

side questions

###: rel - should it be context dependent?

for link relations they can be generic or specific, it depends on the information that relation needs to provide. At least one should consider IANA rels list as it has a lot of useful links that are widespread and reusable.

for actions it more specific names (add-user vs add) can be useful because it makes actions not ambigous.

Ideas to consider

Documentation has two aspects: relations between resources and state-transitions for resources. So We can consider to try to use Resource Blueprint and try to extend it to incorporate resource relations.

Additional considerations (added later)

For human readable format, the profit of the documents is to have overall representation about resources, links and actions + state transitions of each resources it would be great to have a dsl (maybe based on existing ones, like api blueprint) that can describe:

• resources (with properties, and possible links that a client can expect here)
• link relations
• actions
• resource state transitions

based on this information we can build:

• resource graph for our api with
• information about every resource based on resource name, but not it's link
• actions description
• link relations

At the same type there was no URI references in documents at all.