<div dir="ltr"><div>Keep in mind that as of yesterday, unless we revert the change, we are using Integers IDs instead of UUIDs</div><div><br></div><div><a href="https://github.com/pulp/pulp/pull/3549">https://github.com/pulp/pulp/pull/3549</a><br></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Jul 18, 2018 at 9:57 PM, Bihan Zhang <span dir="ltr"><<a href="mailto:bizhang@redhat.com" target="_blank">bizhang@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote"><span class="">On Wed, Jul 18, 2018 at 1:05 PM, Dennis Kliban <span dir="ltr"><<a href="mailto:dkliban@redhat.com" target="_blank">dkliban@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div>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. <br></div><div><br></div><div> - The path parameters in the schema don't reflect the parameters our users should be using for identifying the resources available via REST API. <br></div></div></blockquote><div><br></div></span><div>I'm not convinced that we should use hrefs as the sole identifiers for the resources. </div><div><br></div><div>Here are the reasons I see that we use hrefs as identifiers in a REST API context: </div><div> 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}'</div><div> 2. discoverability, you know exactly how to access resources from hitting the root url (and in a webui can just click)</div><div> 3. You would not need to construct urls from templates </div><div><br></div><div>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.</div><div><br></div><div> 1. Given an {uuid} the client/bindings knows exactly what resource this {uuid} refers to. With hrefs there would be redundant information pulp.repositories('<wbr>repositories/{uuid}') (why do I need to specify repositories twice?)</div><div> 2. Discoverability is done with the schema which contains all the information about available resources/endpoints</div><div> 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)</div><div><br></div><div>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]. </div><div><br></div><div>[0] <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#responses-definitions-object" target="_blank">https://github.com/OAI/<wbr>OpenAPI-Specification/blob/<wbr>master/versions/2.0.md#<wbr>responses-definitions-object</a></div><span class=""><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div></div><div><br></div><div> - The path parameters don't have a description in the schema.</div><div><br></div></div></blockquote></span><div>+1 to updating the schema descriptions for these parameters</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><span class=""><div dir="ltr"><div></div><div>Do others agree with these problem statements? <br></div><div><br></div><div><br></div></div><div class="m_8987155449884470230gmail-HOEnZb"><div class="m_8987155449884470230gmail-h5"><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Jul 18, 2018 at 9:31 AM, Dennis Kliban <span dir="ltr"><<a href="mailto:dkliban@redhat.com" target="_blank">dkliban@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div>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. <br></div><div><br></div><div>The docs generated from our current schema look something like this:</div><div><br></div><div><dt id="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-get--repositories-repository_pk-versions-number-content-"> <code class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-descname">GET </code><code class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-descname">/repositories/{repository_pk}/<wbr>versions/{number}/content/</code><a class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-headerlink" href="https://docs.pulpproject.org/en/3.0/nightly/integration-guide/rest-api/index.html#get--repositories-repository_pk-versions-number-content-" title="Permalink to this definition" target="_blank"></a></dt> <dd><table class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-docutils m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-field-list" frame="void" rules="none"> <colgroup><col class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-field-name"> <col class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-field-body"> </colgroup><tbody valign="top"> <tr class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-field-odd m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-field"><th class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-field-name">Parameters:</th><td class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-field-body"><ul class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-first m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-simple"> <li><strong>number</strong> (<em>integer</em>) – </li> <li><strong>repository_pk</strong> (<em>string</em>) – </li> </ul> </td> </tr> <tr class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-field-even m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-field"><th class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-field-name">Status Codes:</th><td class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-field-body"><ul class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-first m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-last m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-simple"> <li><a class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-reference m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1" target="_blank">200 OK</a> – </li> </ul></td></tr></tbody></table></dd><br></div><div> Since Pulp identifies resources using their HREFs, I am proposing that the schema produce documentation that states:</div><div><br></div><div><dt id="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-get--repositories-repository_pk-versions-number-content-"> <code class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-descname">GET </code><code class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-descname">/{repository_version_href}/con<wbr>tent/</code></dt> <dd><table class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-docutils m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-field-list" frame="void" rules="none"> <colgroup><col class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-field-name"> <col class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-field-body"> </colgroup><tbody valign="top"> <tr class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-field-odd m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-field"><th class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-field-name">Parameters:</th><td class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-field-body"><ul class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-first m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-simple"> <li><strong>repository_version_href</strong> (string) – HREF for the repository version<br></li> </ul> </td> </tr> <tr class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-field-even m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-field"><th class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-field-name">Status Codes:</th><td class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-field-body"><ul class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-first m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-last m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-simple"> <li><a class="m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817gmail-reference m_8987155449884470230gmail-m_-6275621022228469851m_-2856099422503988817external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1" target="_blank">200 OK</a> – </li> </ul></td></tr></tbody></table></dd></div><div><br></div><div>Thoughts? Ideas? All feedback is welcome. Thank you!<br></div></div> </blockquote></div><br></div> </div></div><br></span>______________________________<wbr>_________________<br> Pulp-dev mailing list<br> <a href="mailto:Pulp-dev@redhat.com" target="_blank">Pulp-dev@redhat.com</a><br> <a href="https://www.redhat.com/mailman/listinfo/pulp-dev" rel="noreferrer" target="_blank">https://www.redhat.com/mailman<wbr>/listinfo/pulp-dev</a><br> <br></blockquote></div><br></div></div> <br>______________________________<wbr>_________________<br> Pulp-dev mailing list<br> <a href="mailto:Pulp-dev@redhat.com">Pulp-dev@redhat.com</a><br> <a href="https://www.redhat.com/mailman/listinfo/pulp-dev" rel="noreferrer" target="_blank">https://www.redhat.com/<wbr>mailman/listinfo/pulp-dev</a><br> <br></blockquote></div><br></div>