[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
'id').
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