[Pulp-dev] proposed changes to Pulp 3 auto generated docs

Brian Bouterse bbouters at redhat.com
Mon Jul 23 19:50:43 UTC 2018


Having two ways to refer to objects in the API makes me nervous. I have
some questions/concerns/ideas. I'm also interested to see what dkliban's
bindings produce in terms of a resolution of the swagger issues.

Won't it be problematic with the openapi definitions causing us to have two
schemas? Accepting the data in two forms is one thing, but using openapi to
describe it both ways is something I don't understand well. Are we going to
ship and test two?

I can see why some users would want to refer to things in the api using ID
not an href. I think about the case that when calling publish and referring
to a RepositoryVersion with id=827561, num=3, and for repository=1234. With
an ID alternately accepted, you could call publish and submit
repo_version=827561 instead of repo_version='repositories/1234/version/3/'.
I can see that benefit, but it comes with downsides. Saving/storing a url I
know feels a little strange, but I do see several upsides...

Doing it only with hrefs, ensures those benefits (nice recap btw) will
always be true. Having to submit the references using something like
'repositories/1234/version/3/' will cause any client to store them that
way. I think that's a good thing because someone troubleshooting their
scripts or in katello's db will instead
have 'repositories/1234/version/3/', which they can directly use with HTTP.
I think this is valuable. Otherwise they would have repo version 827561,
which now they have to do extra work to start interacting with that object
via HTTP. Storing urls removes the "templating" step from the
troubleshooter's responsibilities so we're making their job easier.
Spacewise, I don't think the clients benefit hugely from storing 827561
instead of 'repositories/1234/version/3/', but humans do.

I don't know much about the CLI, but if we want to enable a specific user
experience, I think we can find a way to make that work. Overall I think
users should be able to specify things in the most intuitive way possible,
and I don't see how API data formats directly influence that. For example I
think referring to a repository by it's name is the most natural; it's more
natural than 1234 or repositories/1234.


On Thu, Jul 19, 2018 at 8:30 AM, Daniel Alley <dalley at redhat.com> wrote:

> Keep in mind that as of yesterday, unless we revert the change, we are
> using Integers IDs instead of UUIDs
>
> https://github.com/pulp/pulp/pull/3549
>
> On Wed, Jul 18, 2018 at 9:57 PM, Bihan Zhang <bizhang at redhat.com> wrote:
>
>>
>>
>> On Wed, Jul 18, 2018 at 1:05 PM, Dennis Kliban <dkliban at redhat.com>
>> wrote:
>>
>>> I was asked on IRC to state what problems the proposed changes are
>>> trying to address. There are two problems I see with the current OpenAPI
>>> 2.0 schema Pulp's REST API provides.
>>>
>>>  - The path parameters in the schema don't reflect the parameters our
>>> users should be using for identifying the resources available via REST API.
>>>
>>
>> I'm not convinced that we should use hrefs as the sole identifiers for
>> the resources.
>>
>> Here are the reasons I see that we use hrefs as identifiers in a REST API
>> context:
>>     1. Each href provides full context into the resource it identifies.
>> When given a href you would know exactly which resource it is referencing
>> and would never run into the issue of: what is this {uuid} because you know
>> it is a 'repositories/{uuid}'
>>     2. discoverability, you know exactly how to access resources from
>> hitting the root url (and in a webui can just click)
>>     3. You would not need to construct urls from templates
>>
>> But things are different if we look at it from a bindings/client context.
>> The difference is mainly due to how discoverability is done: in the REST
>> API context the user has little prior knowledge to what resources are
>> available, and how to access theses resoruces. But the bindings/client are
>> generated from the schema, which defines exactly how resources are
>> structured, and what the context of each {uuid} is.
>>
>>     1. Given an {uuid} the client/bindings knows exactly what resource
>> this {uuid} refers to.  With hrefs there would be redundant information
>> pulp.repositories('repositories/{uuid}') (why do I need to specify
>> repositories twice?)
>>     2. Discoverability is done with the schema which contains all the
>> information about available resources/endpoints
>>     3. URL construction is done by the client, so the user would also
>> never need to do any url construction themselves (unless we continue to
>> force href only identifiers, in which case they might have to do some url
>> construction to pass as arguments)
>>
>> I don't think hrefs and uuid identifiers are mutually exclusive. I
>> propose that we extend HyperlinkedRelatedFields to accept either href or
>> uuid, and map these HyperlinkedRelatedFields to each other in the schema
>> with openapi definition objects [0].
>>
>> [0] https://github.com/OAI/OpenAPI-Specification/blob/master/
>> versions/2.0.md#responses-definitions-object
>>
>>
>>>
>>>  - The path parameters don't have a description in the schema.
>>>
>>> +1 to updating the schema descriptions for these parameters
>>
>>
>>> Do others agree with these problem statements?
>>>
>>>
>>>
>>> On Wed, Jul 18, 2018 at 9:31 AM, Dennis Kliban <dkliban at redhat.com>
>>> wrote:
>>>
>>>> I am working on improving the OpenAPI 2.0 schema for Pulp 3. I would
>>>> like to get some input on the improvements I am proposing. The schema is
>>>> used to generate our REST API documentation as well as the bindings with
>>>> swagger-codegen.
>>>>
>>>> The docs generated from our current schema look something like this:
>>>>
>>>> GET /repositories/{repository_pk}/versions/{number}/content/
>>>> <https://docs.pulpproject.org/en/3.0/nightly/integration-guide/rest-api/index.html#get--repositories-repository_pk-versions-number-content->
>>>> Parameters:
>>>>
>>>>    - *number* (*integer*) –
>>>>    - *repository_pk* (*string*) –
>>>>
>>>> Status Codes:
>>>>
>>>>    - 200 OK
>>>>    <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1>
>>>>>>>>
>>>>
>>>> Since Pulp identifies resources using their HREFs, I am proposing that
>>>> the schema produce documentation that states:
>>>>
>>>> GET /{repository_version_href}/content/
>>>> Parameters:
>>>>
>>>>    - *repository_version_href* (string) – HREF for the repository
>>>>    version
>>>>
>>>> Status Codes:
>>>>
>>>>    - 200 OK
>>>>    <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1>
>>>>>>>>
>>>>
>>>> Thoughts? Ideas? All feedback is welcome. Thank you!
>>>>
>>>
>>>
>>> _______________________________________________
>>> Pulp-dev mailing list
>>> 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
>>
>>
>
> _______________________________________________
> 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/20180723/3ebdbdf6/attachment.htm>


More information about the Pulp-dev mailing list