[Pulp-dev] pulp 3 bindings change proposal

[Dennis Kliban]

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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20190619/1cc97a3a/attachment.htm>