[katello-devel] API documentation proposal

[Ivan Nečas]

Hi,

I would like to share with you the first artifacts of the effort to 
build a sustainable API documentation (not only) for Katello. Last year 
I've proposed a master thesis topic on the REST api documentation tool 
for Rails framework at local university and after a while a student 
Pavel Pokorny responded positively to this topic and so the story began.

The original idea came from my hobby experimental project active_doc 
(https://github.com/iNecas/active_doc) which aimed to provide DSL to 
describe the code instead of just using plain comments. The advantage of 
this approach is that you have the documentation available on the 
run-time so that you can do additional things like validating that the 
coming requests are consistent with the documentation or serve the 
documentation to the client directly etc.

The project coming from this cooperation is called rails-restapi 
(https://github.com/Pajk/rails-restapi - we haven't found better name 
for that so far:). You can see a sample output at

   http://restapi-likes.rhcloud.com/
   http://restapi-likes.rhcloud.com/apidoc#twitter_example (you can get 
there from the bottom of previous page)
   http://restapi-likes.rhcloud.com/apidoc#twitter_example/lookup


We can divide the whole project into 4 parts:

*1. DSL for describing the requests*, e.g.:

   api :POST, "/organizations/:organization_id/environments", "Create an 
environment in organization"
   param :organization_id, :identifier, :required => true
   param :environment, Hash do
     param :name, :identifier, :required => true, :desc => "Name of the 
new environment, it has to be unique in the organization"
     param :prior, :number, :required => true, :desc => "Id of the prior 
environment. it has to be either Library or an environment at the end of 
a chain"
     param :description, String
   end
   error :code => 400, :desc => "In case the name is already taken or 
the prior is neither Library nor environment at the end of the chain"
   desc <<-DESC
   Long description for the action. You can use RDoc formatting for this 
description.
   DESC
   def create
     # ...
   end

We can describe what path and http method to use do to some action.
With keyword param we specify the arguments we expect. We can also 
specify what value we expect (e.g. with type like Fixnum, String; with 
enumerating acceptable values (["redhat", "custom"]), regular expression 
(/^\w+@\w+\.\w{2,3}$) or with custom validator (:identifier, :number)).
You can also specify what error codes might the action return. With desc 
you can write longer documentation using RDoc formatting.

This DSL can be used before each method of an action. You can similarly 
give some basic documentation for the resource. (You can take a look at 
fully described controller at 
https://github.com/iNecas/katello/blob/restapi/src/app/controllers/api/environments_controller.rb)

*2. Validator for making sure the documentation is up-to date:*

When you say:

   param :provider_type, ["redhat", "custom"]

it would be nice to make sure  that these are the only values we 
support. Therefore restapi provides a validation mode (configurable in 
config/initializers/restapi.rb). When running in this mode, it will fail 
when you try to call it with a value not valid with the description. 
It's ideal combination with running API or CLI tests with this mode so 
that you can make sure that the requests are really consistent with the 
description.

*3. Engine providing the documentation through API
*
The plugin is using Rails Engine architecture to inject it's own routes 
to the application where the documentation can be requested for further 
processing (in JSON format).

*4. HTML client to the documentation server*

There is a sample HTML client provided with the restapi gem, that is 
based on backbone.js. It uses the DOC API described in point 3.

If you run my branch of katello 
(https://github.com/iNecas/katello/tree/restapi - remember to run bundle 
install before and run the app itself in devel mode unless you are 
willing to customize your apache configuration for static assets)

*Automatically generated doc based on CLI tests = API documentation line*

I've put together a tool for kick-starting the first documentation based 
on requests to the API. The idea is to run all cli tests, watch the 
requests and generate the documentation based on the requests, responses 
and config/routes.rb. You can see the results in my branch restapi 
(https://github.com/iNecas/katello/tree/restapi). It's not 100% exact 
but is very useful for starting.

Before you start run bundle install (I've put a gem restapi.0.0.3.kt 
with some tweaks not yet in the upstream version to a custom gem repo 
http://inecas.fedorapeople.org/rubygems/, it's mentioned in the Gemfile).

You can run it in development environment and get the instant feedback 
for you changes (in exchange for longer reload time), in production it's 
much faster because the description not being reloaded.

When you go to:

https://localhost/katello/apidoc

you can see what all possible requests you can make to the API (some 
paths might surprise you but that's what our routes.rb says = we need to 
do some cleenup there).

I've updated documentation for environments a bit so that you can see 
what it might look like:

https://localhost/katello/apidoc#environments

and what a action description might look like:

https://localhost/katello/apidoc#environments/create

There is still some work to do but I would like to hear your feedback, 
suggestions, options on this approach. I hope it's the first step to get 
more consistent and usable API for our project.

-- 
Ivan

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/katello-devel/attachments/20120502/d45595da/attachment.htm>