-
Notifications
You must be signed in to change notification settings - Fork 0
Documenting Hypermedia API
Dmitry Pavlov (@zeldigas)
Mike A., Jorn, David, Ryan, Greg Scott (@gregoryjscott), Tony, ...
Send your tweets to @SergeLyubimov and I'll add you.
Main concern : most of the documentation are done via describing URI templates and actions (i.e. Swagger, API Blueprint). Conveyor:
Attendees: Mike A., Jorn, David, Ryan, Garry Scott, Tony, ..., @snslabs
But the essence of Hypermedia, are relations between resources, but not URIs.
But how to avoid URLs? As client need to know where to try to knock to. But in real 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.
One of the solution worked (Jorn) is to document the relations in a plain text (word/html) and tell to clients that those relations are exists somewhere in ecosystem. which effectively turns to be list of resources with properties.
rel - should it be context dependent? (like 'add-user' vs. 'add' for the user resource).
Let's define documentation as a set of : Resource description, links description and action descriptions.
Resource name (class) properties [ ... ] List of resources/actions we can expect (but they might not be there)
rel names for links might be better considered to be unique, because the more generic they will be the more probability of collision to happen.
What is the purpose of having hypermedia documentation? (to give an idea how to build client not by constructing URL)
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.
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.
what is the benefit to have link relations? if developer will have to deal with documentation. Dynamic and sophisticated clients with forward compatibility.
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.
May be ALPS can do this kind of things? Not sure, as ALPS looks like allow you to list just vocabulary of all relations.