Since I use the API exclusively with RemoteAdmin. API documentation is really important. What do you think of implementating a feature that generates realtime API docs from the code?
Example and Gem here:
https://github.com/Pajk/rails-restapi
http://restapi-likes.rhcloud.com/
Corey Osman
corey@logicminds.biz
Green IT and Datacenter Automation Specialist
> Since I use the API exclusively with RemoteAdmin. API documentation is really important. What do you think of implementating a feature that generates realtime API docs from the code?
>
> Example and Gem here:
>
> https://github.com/Pajk/rails-restapi
> http://restapi-likes.rhcloud.com/
+1 on the concept. However, I think we need to move to API versioning
as part of any major API changes, and confirm the doc tool we use is
compatible with API versioning.
Corey Osman
corey@logicminds.biz
Green IT and Datacenter Automation Specialist
> Since I use the API exclusively with RemoteAdmin. API documentation is
> really important. What do you think of implementating a feature that
> generates realtime API docs from the code?
>
Our plan is to extract the api to its own namespace, e.g.
/api/hosts
we would include version support via an http header, defaulting to latest
api version.
and its funny that you mention this tool, as this is the exact tool we were
planning to use 
we didnt start any work on it just yet, any chance you'll be interested?
Ohad
Example and Gem here:
https://github.com/Pajk/rails-restapi
http://restapi-likes.rhcloud.com/Corey Osman
corey@logicminds.biz
Green IT and Datacenter Automation Specialist
As a coauthor of the tool +1 on that :). The gem was initiated to help
with documentation for http://katello.org/, which is going to
integrate the Foreman soon. It would be nice to share the
documentation style. It also means that, when it shows up there is
something missing in the tool, it's not a big problem to add it there
soon.
I'm finishing a feature that can watch the communication while running
some sort of automated integration tests and produce:
The main goal of the tool is to make the documentation as tied to the
code as possible so that inconsistency can found ASAP. And still not
making the code itself dependent on the documentation.
[1] - http://katello.org/
[2] - https://raw.github.com/iNecas/katello/restapi/src/doc/restapi_examples.yml
I would be very interested.
I am sure we can just add little by little each controller. Start with the simplest and work our way up the biggest most complicated controller (host).
Let me know how you want to move forward.
Corey Osman
corey@logicminds.biz
Green IT and Datacenter Automation Specialist
On Fri, Jun 1, 2012 at 12:29 AM, Corey Osman corey@logicminds.biz wrote:
Since I use the API exclusively with RemoteAdmin. API documentation is really important. What do you think of implementating a feature that generates realtime API docs from the code?Our plan is to extract the api to its own namespace, e.g.
/api/hosts
we would include version support via an http header, defaulting to latest api version.
and its funny that you mention this tool, as this is the exact tool we were planning to use
we didnt start any work on it just yet, any chance you’ll be interested?
Ohad
Example and Gem here:
https://github.com/Pajk/rails-restapi
http://restapi-likes.rhcloud.com/Corey Osman
corey@logicminds.biz
Green IT and Datacenter Automation Specialist
> I would be very interested.
>
> I am sure we can just add little by little each controller. Start with
> the simplest and work our way up the biggest most complicated controller
> (host).
>
Yes - thats the plan
>
> Let me know how you want to move forward.
>
I guess what we need is to create an API name space in the routes file,
then we can split the application controller (for ui) and the api
controller (for api).
I'm guessing we need some common code handling between api/ui (e.g
authentication etc), but for the most part it should not be a big deal.
also, I would guess we don't need to remove the existing json/xml/yaml
handling in the ui controllers, until we are happy with the new controllers.
last thing, is about json representation, I'm in mixed feeling about this
one, as currently, the as_json method is really in the model, and I'm not
sure if it should be in the api 'view' layer.
Corey, do you plan to actively work on that? should we split some work
load, or something?
thanks,
Ohad
Corey Osman
corey@logicminds.bizGreen IT and Datacenter Automation Specialist
On Jun 1, 2012, at 1:48 PM, Ohad Levy wrote:
On Fri, Jun 1, 2012 at 12:29 AM, Corey Osman corey@logicminds.biz wrote:
Since I use the API exclusively with RemoteAdmin. API documentation is
really important. What do you think of implementating a feature that
generates realtime API docs from the code?Our plan is to extract the api to its own namespace, e.g.
/api/hosts
we would include version support via an http header, defaulting to latest
api version.and its funny that you mention this tool, as this is the exact tool we
were planning to usewe didnt start any work on it just yet, any chance you’ll be interested?
Ohad
Example and Gem here:
https://github.com/Pajk/rails-restapi
http://restapi-likes.rhcloud.com/Corey Osman
corey@logicminds.biz
Green IT and Datacenter Automation Specialist
Corey Osman
corey@logicminds.biz
Green IT and Datacenter Automation Specialist
>
>
> I would be very interested.
>
> I am sure we can just add little by little each controller. Start with the simplest and work our way up the biggest most complicated controller (host).
> Yes - thats the plan
>
> Let me know how you want to move forward.
>
> I guess what we need is to create an API name space in the routes file, then we can split the application controller (for ui) and the api controller (for api).
I agree.
>
> I'm guessing we need some common code handling between api/ui (e.g authentication etc), but for the most part it should not be a big deal.
>
> also, I would guess we don't need to remove the existing json/xml/yaml handling in the ui controllers, until we are happy with the new controllers.
>
> last thing, is about json representation, I'm in mixed feeling about this one, as currently, the as_json method is really in the model, and I'm not sure if it should be in the api 'view' layer.
If we could handle custom json representation in the view layer, this would really help out with future 3rd party programs. For example, currently with RemoteAdmin I have to make several API calls to bring together group classes, host classes and all available classes. It would nice to have a custom view for this specific task so it can be rendered on the server instead of a weak mobile device.
Check this out. This would bring all the api calls to the view layer.
http://blog.gomiso.com/2011/06/27/building-a-platform-api-on-rails/
http://blog.dcxn.com/2011/06/22/rails-json-templates-through-rabl/
>
> Corey, do you plan to actively work on that? should we split some work load, or something?
Split the work load. I only have a few hours per day to actually commit to Foreman/Remote Admin development. Even less now that summer has arrived in Portland 
I have to create a bunch of JSON views for my client which I will use the RABL library for. Once I gain some experience with this gem I make further suggestions for the foreman api.
I would think the first step with using a library like RABL would be just to recreate what we already have with to_json calls into the view layer.
There are other gems that do similar json view representations, so we need to agree on what to use first and then go from there.
Corey
thanks,
OhadCorey Osman
corey@logicminds.bizGreen IT and Datacenter Automation Specialist
On Jun 1, 2012, at 1:48 PM, Ohad Levy wrote:
On Fri, Jun 1, 2012 at 12:29 AM, Corey Osman corey@logicminds.biz wrote:
Since I use the API exclusively with RemoteAdmin. API documentation is really important. What do you think of implementating a feature that generates realtime API docs from the code?Our plan is to extract the api to its own namespace, e.g.
/api/hosts
we would include version support via an http header, defaulting to latest api version.
and its funny that you mention this tool, as this is the exact tool we were planning to use
we didnt start any work on it just yet, any chance you’ll be interested?
Ohad
Example and Gem here:
https://github.com/Pajk/rails-restapi
http://restapi-likes.rhcloud.com/Corey Osman
corey@logicminds.biz
Green IT and Datacenter Automation Specialist
