[Pulp-dev] Pulp api seemingly incompatible with generated bindings

Tue Jul 10 13:14:22 UTC 2018

I feel like having users refer to objects by full urls in the CLI would be
suboptimal. Having to deal with all the extra data like scheme, hostname,
port, etc seems like pain for CLI users. Also, using full URLs makes the
CLI feel less like an actual interface to Pulp and more of just an API
wrapper.

Using name only in the CLI seems suboptimal as well because it’s mutable.
Therefore users can’t use stuff like crontab with the CLI because the name
might change.

To give a counterexample to your argument against having two ways to
reference an object: the Ansible Galaxy API exposes both id and href and as
a user I’ve never found this to be a problem. In fact, it’s been convenient
at times.

Another option might to just expose relative urls as object ids to users in
the CLI. I think this perhaps the best of both worlds and good compromise
that would let us remove ids from the API.

David

On Tue, Jul 10, 2018 at 7:28 AM Brian Bouterse <bbouters at redhat.com> wrote:

> I'm concerned that we haven't been very intentional with the introduction
> of 'id' to our API. We added 'id' in a hurry as a stop-gap due to a lack of
> bindings, now bindings are available that don't require id, but we still
> have 'id'. We should remove 'id'. The CLI is the only place I know that is
> using it so these are CLI questions:
>
> How is a user referring to repository f20487e5-51c4-47c7-af22-633adc4bffa9
> easier/better than repositories/f20487e5-51c4-47c7-af22-633adc4bffa9 or
> http://localhost:8000/pulp/api/v3/repositories/f20487e5-51c4-47c7-af22-633adc4bffa9/
> for users? Users will have to copy the UUID anyway, they can just copy the
> URL instead. Also they could just a portion of the URL (no fqn or prefix is
> needed). AIUI the API treats a reference to
> http://localhost:8000/pulp/api/v3/repositories/f20487e5-51c4-47c7-af22-633adc4bffa9/
> and repositories/f20487e5-51c4-47c7-af22-633adc4bffa9 as the same since API
> prefixes are stripped off by DRF.
>
> From a usability perspective, when CLI users are referring to objects, why
> wouldn't users use a more useful term like its name instead? Users this way
> would use 'name=foo' and internally the CLI would just figure it out by
> making requests to resolve that 'name=foo' to a specific object 'foo'. Even
> if 'name' is mutable, at the time the user runs it it won't be ambiguous.
>
> What would it take for us to remove 'id' once again? I advocate that we
> should not have 'two ways' to refer to objects.
>
> @jsherrill this is a complete aside from your important question about who
> will maintain the swagger add-on code. I think the Pulp community needs
> those bindings and so the Pulp community will maintain that add-on code for
> those bindings. I don't expect Katello to maintain Pulp's Ruby bindings. If
> you've found a bug in the Ruby bindings can you file it in Pulp and link to
> it?
>
>
> On Mon, Jul 9, 2018 at 9:34 PM, David Davis <daviddavis at redhat.com> wrote:
>
>> The Pulp 3 CLI relies on the id field as it provides a an immutable way
>> for users to identify objects without using hrefs which wouldn’t make sense
>> in a CLI. So I think we’re keeping the id field.
>>
>> That said, I don’t see how it helps Katello unless Katello stores and
>> uses the id field to identify objects instead of hrefs?
>>
>>
>> On Monday, July 9, 2018, Justin Sherrill <jsherril at redhat.com> wrote:
>>
>>> Hi all,
>>>
>>> I finally had some time to play with these and I do have some concerns.
>>> First i'd say that Dennis' work to get the swagger generation working with
>>> href's seemed to work really well!  I did find one small bug(1) that may be
>>> isolated to the ruby bindings, but seems like a serialization issue
>>> potentially.
>>>
>>> However I do have some concerns.  According to Dennis, upstream swagger
>>> does not seem open to accepting this change that utilizes href's in its api
>>> calls.  This leaves us all in a bit of a pickle as:
>>>
>>> 1) pulp seems to suggest to use hrefs (and may remove ids in the
>>> future?)
>>> 2) swagger does not (and will never?) support referencing objects by
>>> href's in the future
>>>
>>> Thus for katello to use href's, we would need to use an altered version
>>> of swagger that someone maintains.  While the patch is small, I'm not sure
>>> either of our teams are super well positioned to maintain something like
>>> this long term.
>>>
>>> It might make sense for the pulp team to maintain this, as the
>>> requirements are being suggested by the pulp team, however it doesn't seem
>>> like ya'll will actually be using any generated bindings which doesn't seem
>>> like a good dependency.
>>>
>>> It might make sense for the Katello team but I would say we're only
>>> using hrefs because they seem to be what was recommended.  In both cases
>>> its a different technology (java) with a different built system.  I could
>>> see 3 years from now some issue coming up that requires us to update to a
>>> newer swagger version and untangle this when no one that was involved in
>>> this decision was around.  I don't really see either of our teams
>>> maintaining a fork of the swagger code generation as a good long term
>>> solution.
>>>
>>> May I suggest that we either:
>>>
>>>  a) Work harder to get the code change upstream
>>>
>>> or if that does not seem to be going well
>>>
>>>  b) commit to continue responding with ids (in addition to hrefs) in all
>>> object responses
>>>
>>> (1)  https://pulp.plan.io/issues/3843
>>>
>>> On 05/17/2018 06:26 PM, Dennis Kliban wrote:
>>>
>>> I have been able modify the default behavior of swagger-codegen to
>>> produce bindings that use relative URLs to identify resources. The required
>>> changes can be seen here[0]. The compiled jar is available for download
>>> here[1].
>>>
>>> The following command can be used to generate python bindings. Replace
>>> 'python' with 'ruby' and you'll get ruby bindings. The json file is the API
>>> schema returned by the Pulp server at
>>> http://localhost:8000/api/v3/docs/api.json.
>>>
>>> java -jar ./swagger-codegen-cli.jar generate -i
>>> ~/Downloads/pulp3-api.json -l python -o some_directory_name
>>>
>>> [0]
>>> https://github.com/dkliban/swagger-codegen/commit/e31e96769864b73b06bd99f5e20e4720562539b9
>>> [1]
>>> https://repos.fedorapeople.org/pulp/pulp/swagger/swagger-codegen-cli.jar
>>>
>>> On Tue, May 1, 2018 at 11:18 AM, David Davis <daviddavis at redhat.com>
>>> wrote:
>>>
>>>> We’ve exposed IDs and I think the next goal will be to somehow let
>>>> Katello use these IDs. I’ve opened a new story to solicit feedback on how
>>>> this’ll work:
>>>>
>>>> https://pulp.plan.io/issues/3636
>>>>
>>>>
>>>> David
>>>>
>>>> On Tue, May 1, 2018 at 9:14 AM, Brian Bouterse <bbouters at redhat.com>
>>>> wrote:
>>>>
>>>>>
>>>>> On Tue, May 1, 2018 at 7:59 AM, Bryan Kearney <bkearney at redhat.com>
>>>>> wrote:
>>>>>
>>>>>> On 04/30/2018 04:08 PM, Brian Bouterse wrote:
>>>>>> > @asmacdo, checking in on the why is great. I want to try to
>>>>>> articulate
>>>>>> > the benefits as I see them. Other perspectives and discussion are
>>>>>> welcome.
>>>>>> >
>>>>>> > The design of using URLs for referring things is a design whose
>>>>>> goal is
>>>>>> > to minimize complexity as the # of resources grows. The Internet is
>>>>>> a
>>>>>> > useful analogy here. When someone wants to tell me how to find
>>>>>> something
>>>>>> > on Instagram, if the article's name is 'cat_pic432642' and that's
>>>>>> all I
>>>>>> > know, I'm going to have a hard time figuring out the actual URL to
>>>>>> ask
>>>>>> > Instagram's servers for, e.g. /thepostsarehere/cat_pic432642. Even
>>>>>> if I
>>>>>> > did know how Instram's url space was laid out, I have to think
>>>>>> about it
>>>>>> > different from all other web services I interact with; now they're
>>>>>> all
>>>>>> > different. This is the power of the URL itself. All clients and all
>>>>>> > servers can use the uniform resource locator to refer to things. I
>>>>>> think
>>>>>> > this was the main contribution from Tim Berners-Lee that allowed
>>>>>> him to
>>>>>> > implement HTTP which has URIs at its heart.
>>>>>>
>>>>>> But, to Austins Point, if folks are going to interact with Pulp either
>>>>>> from the cli or from Go|rust|python libraries, they will not see the
>>>>>> urls. In your analogy, you would most likely google cat_pic432642  and
>>>>>> never know the url you are going to.
>>>>>>
>>>>>
>>>>> I agree there will be much binding-based usage, and CLI usage, but
>>>>> there will always be users who will use httpie with some bash scripting
>>>>> calls instead. So from that perspective, the goals remain the same they
>>>>> have for years; we need to put forth the best, lowest-complexity REST API.
>>>>>
>>>>>
>>>>>>
>>>>>> -- bk
>>>>>>
>>>>>>
>>>>>
>>>>> _______________________________________________
>>>>> Pulp-dev mailing list
>>>>> Pulp-dev at redhat.com
>>>>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>>>>
>>>>>
>>>>
>>>> _______________________________________________
>>>> Pulp-dev mailing list
>>>> Pulp-dev at redhat.com
>>>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>>>
>>>>
>>>
>>>
>>> _______________________________________________
>>> Pulp-dev mailing listPulp-dev at redhat.comhttps://www.redhat.com/mailman/listinfo/pulp-dev
>>>
>>>
>>>
>>
>> --
>>
>> David
>>
>>
>> _______________________________________________
>> Pulp-dev mailing list
>> Pulp-dev at redhat.com
>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20180710/0c0916d9/attachment.htm>