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

Tue Jul 10 11:27:37 UTC 2018

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/d
>> ocs/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/e31e967698
>> 64b73b06bd99f5e20e4720562539b9
>> [1] https://repos.fedorapeople.org/pulp/pulp/swagger/swagger-cod
>> egen-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/86c04fc0/attachment.htm>