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

Justin Sherrill jsherril at redhat.com
Tue Jul 10 01:16:18 UTC 2018

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 <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
>         <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
>     <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/20180709/6e8cd04f/attachment.htm>

More information about the Pulp-dev mailing list