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 <bizh...@redhat.com> wrote: > > > On Wed, Jul 18, 2018 at 1:05 PM, Dennis Kliban <dkli...@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 <dkli...@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@redhat.com >> https://www.redhat.com/mailman/listinfo/pulp-dev >> >> > > _______________________________________________ > Pulp-dev mailing list > Pulp-dev@redhat.com > https://www.redhat.com/mailman/listinfo/pulp-dev > >
_______________________________________________ Pulp-dev mailing list Pulp-dev@redhat.com https://www.redhat.com/mailman/listinfo/pulp-dev