[Pulp-dev] pulp 3 bindings change proposal

[Matthias Dellweg]

As i am primarily interested in the usability of the bindings, i am ok
with stating, that we know those id's are not uniq anymore, and we know
that it does not impose a problem here.
It still feels like a dirty hack though.
But yes my concerns are addressed.
+1

On Wed, 19 Jun 2019 09:45:56 -0400
Dennis Kliban <dkliban at redhat.com> wrote:

> I didn't get a note in my email, but I did see one on in the list
> archive[0]. So here is my response to it:
> 
> I agree that we could use modified templates to achieve the same
> results. However, that means that we will need to modify templates
> for every language we want to generate bindings in. In both cases the
> generated client code will be exactly the same. From a maintenance
> perspective, it is easier to add a feature to Pulp's REST API that
> produces a modified version of the OpenAPI schema. It also means that
> we can always use the latest versions of the templates shipped with
> openapi-generator.
> 
> The documentation site would continue to distribute an OpenAPI schema
> where each Operation Id is unique.
> 
> Pulp's OpenAPI schema does not currently pass validation because the
> paths are not unique. In order to use the 'href' of each resource as
> the primary identifier, it was necessary to template paths as
> {artifact_href}, {repository_href}, {file_content_href}, etc. This
> schema cannot be used to generate server code. However, it works well
> when generating client code. The non-unique operation ids would be a
> problem for generating a server also. However, they don't produce
> problems when generating client code.
> 
> Does this address your concerns?
> 
> [0] https://www.redhat.com/archives/pulp-dev/2019-June/msg00061.html
> 
> On Wed, Jun 19, 2019 at 8:54 AM Dennis Kliban <dkliban at redhat.com>
> wrote:
> 
> > As pointed out in a recent issue[0], the method names in the
> > bindings generated from Pulp's OpenAPI schema are unnecessarily
> > verbose. Each method name corresponds to an Operation Id in the
> > OpenAPI schema. The Operation Id is also used as an HTML anchor in
> > the REST API docs[1].
> >
> > It is possible to generate a schema where each Operation Id is
> > shorter, but then the Operation Ids are not unique and all the
> > linking in the REST API documentation breaks. We can avoid this
> > problem by keeping the long Operation Id for the schema generated
> > for the docs and only using short Operation Ids when generating the
> > schema for the bindings.
> >
> > The difference in usage of the bindings can be seen here[2].
> >
> > Is there any objection to including such a change in time for RC 3?
> >
> > [0] https://pulp.plan.io/issues/4989
> > [1] https://docs.pulpproject.org/en/3.0/nightly/restapi.html
> > [2] https://pulp.plan.io/issues/4989#note-1
> >  




Herzliche Grüße aus München

Matthias Dellweg
______________________________________________________ 
Dr. Matthias M. Dellweg

(Open Source Software Engineer)

Tel: +49 (0)89 452 35 38-12
Fax: +49 (0)89 452 35 38-290
E-Mail: dellweg at atix.de

ATIX - The Linux & Open Source Company

ATIX Informationstechnologie und Consulting AG
Parkring 15
85748 Garching bei München
www.atix.de


Registergericht: Amtsgericht München, Registernummer: HRB 168930
USt.-Id.: DE209485962
Vorstand: Thomas Merz (Vors.), Mark Hlawatschek
Vorsitzender des Aufsichtsrats: Dr. Martin Buss
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20190619/604cc6f9/attachment.sig>