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

Tue Jul 24 01:51:52 UTC 2018

I've made a work in progress PR[0] that demonstrates the changes I was
suggesting.

[0] https://github.com/pulp/pulp/pull/3561

On Mon, Jul 23, 2018 at 3:50 PM, Brian Bouterse <bbouters at redhat.com> wrote:

> 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/ver
>>> sions/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
>>
>>
>
> _______________________________________________
> 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/1145d6ee/attachment.htm>