Documenting the steps needed to get to a given resource


#1

Hi all,

I see and like the RamlToHtml project, and have considered using some other frameworks to possibly do something similar.

My topic however is trying to figure out how to provide documentation that allows a reader to easily understand how a given resource they are looking at, is reached. By that I mean, at least to me pretty much all Rest API docs flat list the resources and the nicer docs like RAML and Swagger, have GET/POST/PUT/DELETE snippets and examples and such. However, what is lacking is that I can jump in to pretty much any resource, but have no clue the calls needed to allow for the resource I am looking at to be called. For example, and this is probably more true in HATEOAS based APIs than non-HATEOAS APIs, but supposing I need to get a list of contacts for a specific user. I’d need the user ID to get the contacts for. How do we get that user ID? There are any number of answers, but let’s say in this ficticious API the only way is via a search call using first/last name. I find the user, it returns back some user info including the ID. Now I can make my call to the /contacts/ or /users//contacts. When reading the documentation for the /contacts resource, as far as I’ve ever seen there is never any info that explains HOW to get the user-id. Mind you…this is a simplistic example, and the documentation for the property could provide info that says “make a call to /search?name=… to get the details of the user and the id” but my point is, there is no good way to provide links to the “parent” call or series of calls needed to allow a given resource to be callable.

I guess I am asking what do people do now… do they provide in their documentation of given properties actual links or hints in some way? Is there a way we can provide in documentation something like {call: [resource1, resource2…]} such that the RAML tooling could see that and then find the other resources, build links to them and add that to the generated HTML output?

More to the point… is there anything in RAML and Raml2HTML that does this now that I am not seeing in documentation anywhere?


#2

Hi @justjacksonn,

this is a really nice use case :wink: I guess you are asking for hypermedia or HATEOAS style API documentation. Of course something like that could be build into a documentation using transformation tools like php-RAML2HTML (https://github.com/mikestowe/php-raml2html). BUT, something like that does not exists and has to be implemented. Although, I like the idea and already thought about having a browserable option, besides having the console for clicking through resources and the details, to explore your datasets as the HAL browser supports. BUT, that also means some intelligent from the documentation creation tools linking all those resources together as you don’t have links on level 2 APIs (non-HATEOS). With RAML 1.0 though, you could create your own x- type linking the resources for the browser tool. (Just ideas poping up in my mind) :smiley:

Do you have any other ideas? I think out of this conversation - we could create something really cool actually. Although, this will not create level 3 APIs (HATEOS), but the x- types could be used especially for the browsing tool to identify links. What do you think?

Cheers,
Christian


#3

Oh.I have a ton of ideas :). For me, if I work on something like this I’ll be using ReactJS and Bootstrap to build the UI with (I’ve posted before about trying to go this route). But I am not that adept at the client side at this time to really make good progress in any sort of decent time frame.

I’ll have to read up on the 1.0 spec a bit more, I am hoping it’s out soon though! I’d like to use 1.0 vs .8 (looks better to companies for some reason ;).

I do believe what I am proposing is possible, but would involve a bit of work for sure to properly match up links to other generated pages/anchors, and as seen in other forum posts regarding pop-ups, hide/show sections, etc… there are numerous ways the UI could be done… any of which could be good or bad depending on who you ask.

I did however want to make sure before I even consider doing something like this, that it wasn’t yet implemented and I just didn’t read/see it, so that is answered. Thanks.


#4

Please go ahead and read through the 1.0 spec as I think we could use some of the new features to implement this. It would be a great addition and it is possible. :wink: Have you seen the UIs for HATEOS APIs already?


#5

No… actually I haven’t found any example of a HATEOAS based API doc… do you have some references? Love to take a look. I am however also thinking “flat” resource docs… for example many that don’t use HATEOAS have tons of resources like /users, /accounts, /contacts, etc… they may inter-relate, yet they are not HATEOAS driven, so often they are called document driven…where by API developers need to read the docs and/or programming guides to learn what URLs to call and how to use them. Frankly I think all APIs need to have guides built around them to instruct how to use them properly. I love the detailed docs RAML is capable of, but I still wouldn’t have it be the sole documentation for a more robust API. I’d want SDKs, sample code, guides, videos, etc to give consumers the best possible chance to succeed in using the API.


#6

Agreed. What I have seen in a couple of API documentation are code samples and this is something I’m pushing as much as possible. Unfortunately, I am a Java developer only and my language skills in JavaScript are “limited” :smiley: So I can’t program it by myself and I am only able to give those ideas :smiley: But to come back on it, something like that would already increase the documentation experience.

(btw, learning JavaScript/NodeJS, etc right now) :wink:

http://audreydemo.aws.af.cm/hal-browser/#/ - one example of HAL browser


#7

Does RAML support the ability to specify links in responses to document them? Actually that should be part of the JSON Schema (or XSD) that would specify the links that are returned.

The bigger problem, that should also be addresses, is ACL… such that a given documentation of a resource would list the different access right bits… for example if you have an Admin, End User and Guest, you could somehow click on those and see what response is returned based on the user/role selected. This would naturally make it’s way down to the response links, response header details, etc. Now we’re talking a utopia of documentation, but again that adds another complex layer of logic. To take it a step further… links would need some sort of documentation… when you go to the resource the link refers to, there is naturally the resource documentation. However, there should be some “short” form of documentation that can be displayed in the resource where the response link shows up under as well. Otherwise, every single resource needs to know about all the response link types possible. To make it more HATEOAS discoverable like… when I update the JSON Schema to include a new link type…I don’t want to have to update the documentation of every resource that refers to that link response as well. Instead, the document generator should be able to “reach in” to the documentation of referenced links, grab the “short” description, and insert that into the response documentation of the resource referencing the link. Holy crap that is confusing to read… be much easier to white board, but hopefully it’s somewhat understandable. If not, well… I guess I’ll just need to implement it some day to make it understandable. :wink:

I too am learning nodejs… you really should take a jump in to ReactJS. The speed is amazing, and the concepts of uni-directional data flow make a lot of sense, very similar to game development/rendering. There is a bit of a learning curve, but the ability to build components and reuse them all over is very good, and the rendering speed is second to none until browsers themselves incorporate the “diffing” that ReactJS does.