[Pulp-dev] Pulp3 MVP Refinement Next Steps

[Tomas Strachota]

Hello,
thank you, David, for including me. I added some observations inline.

On Fri, Mar 10, 2017 at 7:08 PM, David Davis <daviddavis at redhat.com> wrote:
> Yea, I’m including @tstrachota here to correct me if I’m wrong. In
> foreman/katello, they use apipie to document the api and this produces the
> structure in json:
>
> https://github.com/Apipie/apipie-rails
>
> The CLI is written using hammer-cli. It takes the apipie json (which it also
> caches) and turns it into commands/options. Here’s that code:
>
> https://github.com/theforeman/hammer-cli/tree/master/lib/hammer_cli/apipie
>

If you're interested, there's some examples about usage here:
 https://github.com/theforeman/hammer-cli/blob/master/doc/creating_apipie_commands.md#creating-commands-for-restful-api-with-apipie
and here:
 https://github.com/theforeman/hammer-cli/blob/master/doc/developer_docs.md#hammer-development-docs

> I’m not sure if it’s generic enough for us to use though unfortunately.
> Maybe it could be though? Also, it’s in Ruby of course.

The code that takes care about generating the options from apipie docs
can be replaced with some other adaptor to another docs source but the
main advantage is in apipie-bindings that take care of downloading and
caching the docs.
You would probably need to either implement some equivalent of
apipie-bindings for your documentation system or equivalent of
apipie-rails generating compatible json output for Python.

>
> Lastly, here’s just an example of the user set of cli commands. It looks
> longer than it ought to be due to i18n of the field names but take a look at
> create/update/delete:
>
> https://git.io/vyrsy

BTW I've had a prototype of output field definition in the api docs.
That reduced the CLI definition to just list of enabled commands in
most cases. In the end we stepped back from it because devs were
afraid of having to maintain field definition at two places in case we
needed to tune something on the CLI side.

>
> At the very least, I think hammer-cli is a great example of one direction we
> could take in order to eliminate redundant code and make our CLI mostly
> dynamic.
>

Dynamic nature of the CLI can save you some work and, to some extent,
it is able to reconfigure according to the version of server it
connects to. As a positive side effect it forces you to have the api
docs up to date. On the other hand it can also lead to bugs in CLI
when developers change documentation of an api parameter and related
CLI commands aren't covered with tests.

>
>
>
> David
>
> On Fri, Mar 10, 2017 at 12:48 PM, Sean Myers <sean.myers at redhat.com> wrote:
>>
>> On 03/03/2017 04:09 PM, David Davis wrote:
>> > This is essentially what foreman and katello do, and it works great.
>> > They
>> > get an json export of the REST API structure from the server and then
>> > map
>> > each endpoint to a command and the parameters to options. One can still
>> > override the default functionality for each command (or add extra
>> > commands)
>> > but for most commands, there isn't any code required.
>>
>> I'd love to avoid wheel reinvention here, got a link handy?
>>
>