>>
>>>
>>>>
>>>>
>>>>> So my understanding is the new API is fully self documenting. At this
>>>>> point, I think it must be incomplete as:
>>>>>
>>>>> GET /api
>>>>>
>>>>> returns:
>>>>>
>>>>> {"links":{"List all bookmarks.":"/api/bookmarks","List all
>>>>> architectures.":"/api/architectures","Show
>>>>> status.":"/api/status","Show available links.":"/api","List all
>>>>> users.":"/api/users","List all operating
>>>>> systems.":"/api/operatingsystems"}}
>>>>>
>>>>> Looks like many of the supported REST collections in the classic API
>>>>> are missing. e.g. - /api/hosts
>>>>
>>>> true, we are slowly adding them in,the overall idea is
>>>> 1. create a new name space which is versioned.
>>>> 2. copy the existing api as v1.
>>>>
>>>> once we get v1 working, we'll start working on v2.
>>>>>
>>>>> That said, I love the fact that we can query the new API for it's
>>>>> capabilities.
>>>>>
>>>>> Hmm. I see why… it's another WIP. I took a quick look at the code and
>>>>> it looks straightforward enough, if I can ever get some free time. I
>>>>> think extending the new API is almost certainly something ruby nubies
>>>>> (like me) could tackle in chucks, as most of the heavy lifting has
>>>>> been done.
>>>>>
>>>>> e.g.: bookmarks:
>>>>> ./app/controllers/api/v1/bookmarks_controller.rb
>>>>> ./app/views/api/v1/bookmarks
>>>>> ./app/views/api/v1/bookmarks/create.json.rabl
>>>>> ./app/views/api/v1/bookmarks/index.json.rabl
>>>>> ./app/views/api/v1/bookmarks/show.json.rabl
>>>>> ./app/views/api/v1/bookmarks/update.json.rabl
>>>>> ./test/functional/api/v1/bookmarks_controller_test.rb
>>>>>
>>>>> Too bad we have to exchange a self-writing API for a self-documenting
>>>>> API. 
>>>>
>>>> Well, writing the code and docs in one place, and eventually
>>>> automatically generating Ruby Binding, Python Bindings and a CLI, is not
>>>> that bad right?
>>> Where is this? Or it related to the fact you can query the api for its
>>> capabilities?
>>
>> there is a rake task to generate the cli, try:
>>
>> rake apipie:client
> So, I ran: RAILS_ENV=production bundle exec rake apipie:client
>
> and it built the following files in my foremanhomedir. (Need to figure
> out how to build somewhere else I think.)
>
> create README
> create Gemfile
> create Rakefile
> create foreman_client.gemspec
> create lib/foreman_client.rb
> create lib/foreman_client/base.rb
> create lib/foreman_client/rest_client_oauth.rb
> create lib/foreman_client/version.rb
> create bin/foreman_client
> chmod bin/foreman_client
> create lib/foreman_client/cli_command.rb
> create lib/foreman_client/commands/architecture.thor
> create lib/foreman_client/resources/architecture.rb
> create lib/foreman_client/commands/operating_system.thor
> create lib/foreman_client/resources/operating_system.rb
> create lib/foreman_client/commands/user.thor
> create lib/foreman_client/resources/user.rb
> create lib/foreman_client/commands/bookmark.thor
> create lib/foreman_client/resources/bookmark.rb
> create lib/foreman_client/commands/home.thor
> create lib/foreman_client/resources/home.rb
>
> I played a little bit and it looks like a good starting point, and the
> benefits are probably going to be worth accepting the issues Thor
> brings to the table. (Great find BTW).
>
> So some questions. (If you don't know the answers I will dig into the code.)
> 1) Do we need to rebuild the CLI, every time we make changes to the
> API code, or does the build CLI actually parse foreman for it's
> capabilities at run time?
Yes, as it is designed now we have to regenerate the client whenever the
api changes.
But Apipie is young project and things may change to fit our needs better.
> 2) If we use this as a base for foreman, shall we manage in a separate
> repo? (Thinking yes, but don't really know a starting point.)
I started with bindings (without cli) it is created with
rake apipie:client:bindings[_api]
and the actual code lives here https://github.com/theforeman/foreman_api
I'm going to keep it up to date as work on the API will go on.
The gem should be soon on rubygems.org and should have some docs.
To follow simillar pattern with the client seems a good idea to me. Ohad?
> 3) It looks like what gets built won't be very usable off the shelf…
> I'm wondering how to go about customizing how the cli gets built.
> (Basically I don't want to build in and then customize it.)
The generated CLI somehow works, but definitely needs some customization
and defining development workflow which will probably be different from
the one of bindings.
I believe the apipie CLI generator is a starter and the devs are open to
suggestions and patches.
For a start I would suggest to add option to apipie to generate the CLI
so it requires the bindings to avoid duplicit code.
> 4) What's the story with authentication, I see oauth? WIll the CLI
> need to use oauth, and if so, how do we configure that?
Both the oauth and the username/password are supported.
Foreman api looks in the request header and use what you choosed.
> 5) Any thoughts on a dev workflow here? Or should we focus on fleshing
> out the API, and cross that bridge later? (Thinking if you have folks
> working on the fleshing out the API, I can try to find time to work on
> the CLI in parallel, so that when the API is complete we will
> hopefully be a lot closer to having a functioning hammer.)
I think the workflow depends on what you expect from the CLI.
It would make sense to me to focus on improving the apipie to make it
able to generate client
as close as possible to the desired result and find a way
how the upgrades don't break the eventual customized code too much.
Martin
···
On 08/07/2012 06:41 PM, Brian Gupta wrote:
> On Sun, Aug 5, 2012 at 7:45 AM, Ohad Levy wrote:
>> On Sun, Aug 5, 2012 at 2:34 PM, Brian Gupta >> wrote:
>>> On Aug 5, 2012 2:34 AM, "Ohad Levy" wrote:
>>>> On Sat, Aug 4, 2012 at 3:54 AM, Brian Gupta >>>> wrote:
and for the ruby binding
https://github.com/mbacovsky/foreman_api
Ohad
-Brian
