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

Jeff Ortel jortel at redhat.com
Tue Jul 10 17:43:05 UTC 2018

+1 to supporting both URI and PK (probably better named 'pk' instead of 

On 07/10/2018 08:14 AM, David Davis wrote:
> 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 
> <mailto: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
>     <mailto: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
>         <mailto: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 <mailto: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 <mailto:bbouters at redhat.com>> wrote:
>>                     On Tue, May 1, 2018 at 7:59 AM, Bryan Kearney
>>                     <bkearney at redhat.com
>>                     <mailto: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 <mailto:Pulp-dev at redhat.com>
>>                     https://www.redhat.com/mailman/listinfo/pulp-dev
>>                 _______________________________________________
>>                 Pulp-dev mailing list
>>                 Pulp-dev at redhat.com <mailto:Pulp-dev at redhat.com>
>>                 https://www.redhat.com/mailman/listinfo/pulp-dev
>>             _______________________________________________
>>             Pulp-dev mailing list
>>             Pulp-dev at redhat.com <mailto:Pulp-dev at redhat.com>
>>             https://www.redhat.com/mailman/listinfo/pulp-dev
>         -- 
>         David
>         _______________________________________________
>         Pulp-dev mailing list
>         Pulp-dev at redhat.com <mailto: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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20180710/8bdf6fe9/attachment.htm>

More information about the Pulp-dev mailing list