<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Mon, Jul 9, 2018 at 9:16 PM, Justin Sherrill <span dir="ltr"><<a href="mailto:jsherril@redhat.com" target="_blank">jsherril@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<div bgcolor="#FFFFFF">
<p>Hi all,</p>
<p>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.<br></p></div></blockquote><div>Thank you for filing the issue. We are going to add it to our next sprint on Friday. <br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="#FFFFFF"><p>
</p>
<p>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:</p>
<p>1) pulp seems to suggest to use hrefs (and may remove ids in the
future?) <br>
2) swagger does not (and will never?) support referencing objects
by href's in the future</p></div></blockquote><div>I would like to clear up the language we are using.</div><div><br></div><div>swagger[0] is the former name for OpenAPI 2.0, which is a standard for richly defining REST API schema. <br></div><div><br></div><div>Pulp 3 has a REST API endpoint that serves it's OpenAPI 2.0 schema. We are constantly working to improve the accuracy and level of detail of this OpenAPI 2.0 schema. We use the schema to generate our REST API documentation. Our CLI is going to rely on the schema to inform the user what all interactions with the server are available and what parameters are needed. We have recently decided to start using pyswagger[1] as the client library in the CLI. I have not been able to find a similar client for Ruby. I welcome others to search for one.</div><div><br></div><div>Another solution for taking advantage of the OpenAPI 2.0 schema definition on the client side is to generate a client using swagger-codegen[2]. swagger-codegen is a tool that takes OpenAPI 2.0 schema definition as an input and produces a client library (bindings) in a language of your choice. It does so by taking parameters it finds in the schema and inserts them into templates for the specific language requested. The templates bundled with swagger-codegen assume that the user will use "path parameters" to identify resources. This behavior is not compatible with Pulp because Pulp identifies resources using URIs. <br></div><div></div><div><br></div><div>I asked in #swagger on freenode about changing the behavior of swagger-codegen and I was recommended to update the templates for Ruby, Python, and any other languages we want to support. That is how users of swagger-codegen are supposed to customize the behavior of swagger-codegen. <br></div><div><br></div><div>Instead of modifying each language's template, I found it easier to modify the behavior of swagger-codegen. As a result, we can generate working bindings in all the languages supported by swagger-codegen. <br></div><div><br></div><div>[0] <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md" target="_blank">https://github.com/OAI/OpenAPI<wbr>-Specification/blob/master/ver<wbr>sions/2.0.md</a></div><div>[1] <a href="https://github.com/pyopenapi/pyswagger" target="_blank">https://github.com/pyopenapi/p<wbr>yswagger</a><br></div><div>[2] <a href="https://swagger.io/tools/swagger-codegen/" target="_blank">https://swagger.io/tools/swagg<wbr>er-codegen/</a><br></div><div> </div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="#FFFFFF">
<p>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. <br></p></div></blockquote><div>I based my changes on the master branch, which will be the next, 2.4.0, release of swagger-codegen. I have also checked that a similar patch can be used for modifying the behavior on the 3.0.0 branch. We should not have compatibility problems with swagger-codegen 2.y and a similar approach can be used with 3.y when that becomes the stable release. <br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="#FFFFFF"><p>
</p>
<p>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. <br></p></div></blockquote><div>We want to make the modified version of swagger-codegen available to all Pulp users. Our users will then have an option of using an unpatched version of swagger-codegen to generate bindings that require the user to remember both UUIDs and HREFs or using our version of swagger-codegen that will produce bindings that use URI as the identifier in all cases. <br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="#FFFFFF"><p>
</p>
<p>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.<br></p></div></blockquote><div><br></div><div>The Pulp team will have ownership of the modified swagger-codegen as it will be providing value to all users that want to integrate with Pulp 3. <br></div><div><br></div><div>We do not intend to publish bindings for any particular language because each Pulp installation will require a different set of bindings based on which plugins are installed. <br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="#FFFFFF"><p>
</p>
<p>May I suggest that we either:</p>
<p> a) Work harder to get the code change upstream</p>
<p>or if that does not seem to be going well<br>
</p>
<p> b) commit to continue responding with ids (in addition to hrefs)
in all object responses</p>
<p>(1) <a class="m_4823202989363056534m_7743374761030605464m_-2203371121909688876gmail-m_1462400485138334858gmail-m_2005859604517307367moz-txt-link-freetext" href="https://pulp.plan.io/issues/3843" target="_blank">https://pulp.plan.io/issues/38<wbr>43</a></p></div></blockquote><div>I don't think we plan to stop responding with IDs. However, our REST API will continue to expect HREFs in body parameters that reference resources. This leaves you with 3 options:</div><div><br></div><div> - Write your own client for interacting with Pulp 3</div><div><br></div><div> - use the upstream version of swagger-codegen to generate bindings and keep track of IDs and HREFs <br></div><div><br></div><div> - use the version of swagger-codegen shipped by the Pulp team and only keep track of HREFs<br></div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="#FFFFFF"><p><br>
</p><div><div class="m_4823202989363056534m_7743374761030605464m_-2203371121909688876gmail-m_1462400485138334858gmail-h5">
<br>
<div class="m_4823202989363056534m_7743374761030605464m_-2203371121909688876gmail-m_1462400485138334858gmail-m_2005859604517307367moz-cite-prefix">On 05/17/2018 06:26 PM, Dennis Kliban
wrote:<br>
</div>
<blockquote type="cite">
<div dir="ltr">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]. <br>
<br>
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 <a class="m_4823202989363056534m_7743374761030605464m_-2203371121909688876gmail-m_1462400485138334858gmail-m_2005859604517307367external" href="http://localhost:8000/api/v3/docs/api.json" target="_blank">http://localhost:8000/api/v3/d<wbr>ocs/api.json</a>.
<br>
<br>
java -jar ./swagger-codegen-cli.jar generate -i
~/Downloads/pulp3-api.json -l python -o some_directory_name<br>
<br>
[0] <a href="https://github.com/dkliban/swagger-codegen/commit/e31e96769864b73b06bd99f5e20e4720562539b9" target="_blank">https://github.com/dkliban/swa<wbr>gger-codegen/commit/e31e967698<wbr>64b73b06bd99f5e20e4720562539b9</a><br>
[1] <a href="https://repos.fedorapeople.org/pulp/pulp/swagger/swagger-codegen-cli.jar" target="_blank">https://repos.fedorapeople.org<wbr>/pulp/pulp/swagger/swagger-cod<wbr>egen-cli.jar</a><br>
</div>
<div class="gmail_extra"><br>
<div class="gmail_quote">On Tue, May 1, 2018 at 11:18 AM, David
Davis <span dir="ltr"><<a href="mailto:daviddavis@redhat.com" target="_blank">daviddavis@redhat.com</a>></span>
wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<div dir="ltr">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:
<div><br>
</div>
<div><a href="https://pulp.plan.io/issues/3636" target="_blank">https://pulp.plan.io/issues/36<wbr>36</a><span class="m_4823202989363056534m_7743374761030605464m_-2203371121909688876gmail-m_1462400485138334858gmail-m_2005859604517307367HOEnZb"><font color="#888888"><br>
</font></span></div>
</div>
<div class="gmail_extra"><span class="m_4823202989363056534m_7743374761030605464m_-2203371121909688876gmail-m_1462400485138334858gmail-m_2005859604517307367HOEnZb"><font color="#888888"><br clear="all">
<div>
<div class="m_4823202989363056534m_7743374761030605464m_-2203371121909688876gmail-m_1462400485138334858gmail-m_2005859604517307367m_-4971748094304000821gmail_signature">
<div dir="ltr">
<div>
<div dir="ltr">
<div>
<div dir="ltr">
<div><br>
</div>
<div>David<br>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<br>
</font></span>
<div class="gmail_quote">
<div>
<div class="m_4823202989363056534m_7743374761030605464m_-2203371121909688876gmail-m_1462400485138334858gmail-m_2005859604517307367h5">On Tue, May 1, 2018 at 9:14 AM, Brian
Bouterse <span dir="ltr"><<a href="mailto:bbouters@redhat.com" target="_blank">bbouters@redhat.com</a>></span>
wrote:<br>
</div>
</div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<div>
<div class="m_4823202989363056534m_7743374761030605464m_-2203371121909688876gmail-m_1462400485138334858gmail-m_2005859604517307367h5">
<div dir="ltr">
<div class="gmail_extra"><br>
<div class="gmail_quote"><span>On Tue, May 1,
2018 at 7:59 AM, Bryan Kearney <span dir="ltr"><<a href="mailto:bkearney@redhat.com" target="_blank">bkearney@redhat.com</a>></span>
wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><span>On
04/30/2018 04:08 PM, Brian Bouterse
wrote:<br>
> @asmacdo, checking in on the why
is great. I want to try to articulate<br>
> the benefits as I see them. Other
perspectives and discussion are
welcome.<br>
> <br>
> The design of using URLs for
referring things is a design whose
goal is<br>
> to minimize complexity as the #
of resources grows. The Internet is a<br>
> useful analogy here. When someone
wants to tell me how to find something<br>
> on Instagram, if the article's
name is 'cat_pic432642' and that's all
I<br>
> know, I'm going to have a hard
time figuring out the actual URL to
ask<br>
> Instagram's servers for, e.g.
/thepostsarehere/cat_pic432642<wbr>.
Even if I<br>
> did know how Instram's url space
was laid out, I have to think about it<br>
> different from all other web
services I interact with; now they're
all<br>
> different. This is the power of
the URL itself. All clients and all<br>
> servers can use the uniform
resource locator to refer to things. I
think<br>
> this was the main contribution
from Tim Berners-Lee that allowed him
to<br>
> implement HTTP which has URIs at
its heart.<br>
<br>
</span>But, to Austins Point, if folks
are going to interact with Pulp either<br>
from the cli or from Go|rust|python
libraries, they will not see the<br>
urls. In your analogy, you would most
likely google cat_pic432642 and<br>
never know the url you are going to.<br>
</blockquote>
</span>
<div><br>
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.<br>
</div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<span class="m_4823202989363056534m_7743374761030605464m_-2203371121909688876gmail-m_1462400485138334858gmail-m_2005859604517307367m_-4971748094304000821m_4138795520150130818HOEnZb"><font color="#888888"><br>
-- bk<br>
<br>
</font></span></blockquote>
</div>
<br>
</div>
</div>
<br>
</div>
</div>
<span>______________________________<wbr>_________________<br>
Pulp-dev mailing list<br>
<a href="mailto:Pulp-dev@redhat.com" target="_blank">Pulp-dev@redhat.com</a><br>
<a href="https://www.redhat.com/mailman/listinfo/pulp-dev" rel="noreferrer" target="_blank">https://www.redhat.com/mailman<wbr>/listinfo/pulp-dev</a><br>
<br>
</span></blockquote>
</div>
<br>
</div>
<br>
______________________________<wbr>_________________<br>
Pulp-dev mailing list<br>
<a href="mailto:Pulp-dev@redhat.com" target="_blank">Pulp-dev@redhat.com</a><br>
<a href="https://www.redhat.com/mailman/listinfo/pulp-dev" rel="noreferrer" target="_blank">https://www.redhat.com/mailman<wbr>/listinfo/pulp-dev</a><br>
<br>
</blockquote>
</div>
<br>
</div>
<br>
<fieldset class="m_4823202989363056534m_7743374761030605464m_-2203371121909688876gmail-m_1462400485138334858gmail-m_2005859604517307367mimeAttachmentHeader"></fieldset>
<br>
<pre>______________________________<wbr>_________________
Pulp-dev mailing list
<a class="m_4823202989363056534m_7743374761030605464m_-2203371121909688876gmail-m_1462400485138334858gmail-m_2005859604517307367moz-txt-link-abbreviated" href="mailto:Pulp-dev@redhat.com" target="_blank">Pulp-dev@redhat.com</a>
<a class="m_4823202989363056534m_7743374761030605464m_-2203371121909688876gmail-m_1462400485138334858gmail-m_2005859604517307367moz-txt-link-freetext" href="https://www.redhat.com/mailman/listinfo/pulp-dev" target="_blank">https://www.redhat.com/mailman<wbr>/listinfo/pulp-dev</a>
</pre>
</blockquote>
<br>
</div></div></div>
<br>______________________________<wbr>_________________<br>
Pulp-dev mailing list<br>
<a href="mailto:Pulp-dev@redhat.com" target="_blank">Pulp-dev@redhat.com</a><br>
<a href="https://www.redhat.com/mailman/listinfo/pulp-dev" rel="noreferrer" target="_blank">https://www.redhat.com/mailman<wbr>/listinfo/pulp-dev</a><br>
<br></blockquote></div><br></div></div>