<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=Windows-1252">
</head>
<body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;">
On Jun 23, 2015, at 2:47 PM, Ed Cranford <<a href="mailto:ed.cranford@RACKSPACE.COM">ed.cranford@RACKSPACE.COM</a>> wrote:<br>
<div><br class="Apple-interchange-newline">
<blockquote type="cite">
<div dir="ltr" style="font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; font-size: 12pt; background-color: rgb(255, 255, 255); font-family: Calibri, Arial, Helvetica, sans-serif; position: static; z-index: auto;">
<div style="margin-top: 0px; margin-bottom: 0px;">The app-resource spec [1] is as much documentation as we have on the new resources at present. It does illustrate some imagined healthy interactions with the proposed API, though looking at the mentioned Glance
example I can see several ways we can improve our specs, for example by explaining more verbosely not just what each response might look like, but conceptually what has been asked for and what is being returned. There is clear precedent for modifying specs
after ratification, so there should be no problem modifying even the app-resource spec to make our goals clearer.<br>
</div>
<div style="margin-top: 0px; margin-bottom: 0px;"><br>
</div>
<div style="margin-top: 0px; margin-bottom: 0px;">The linked review [2] is the first of a planned series of such with the goal of implementing that spec. It creates a new data model for one of the three proposed resources and then exposes CRUD actions on that
resource. Future reviews will incrementally add the other resources, add stronger data validation, integrate the new resources into the engine, and finally deprecate the obsolete resources and interactions.<span class="Apple-converted-space"> </span><br>
</div>
<div style="margin-top: 0px; margin-bottom: 0px;"><br>
</div>
<div style="margin-top: 0px; margin-bottom: 0px;">We appreciate your advice on cleaner reviews and better design, especially since we're asking that you take the time to look over them, but we are primarily seeking your advice on our adherence to the API WG's
guidelines, and if amending the spec to add detail and clarity is necessary we won't hesitate.</div>
<div style="margin-top: 0px; margin-bottom: 0px;"><br>
</div>
<div style="margin-top: 0px; margin-bottom: 0px;">Thank you very much for your help.</div>
<div style="margin-top: 0px; margin-bottom: 0px;"><br>
</div>
<div style="margin-top: 0px; margin-bottom: 0px;">[1]<span class="Apple-converted-space"> </span><a href="https://github.com/stackforge/solum-specs/blob/master/specs/liberty/app-resource.rst">https://github.com/stackforge/solum-specs/blob/master/specs/liberty/app-resource.rst</a></div>
<div style="margin-top: 0px; margin-bottom: 0px;">[2]<span class="Apple-converted-space"> </span><a href="https://review.openstack.org/#/c/185147/">https://review.openstack.org/#/c/185147/<span class="Apple-converted-space"> </span></a><br>
</div>
</div>
</blockquote>
<div><br>
</div>
<div>A couple of us reviewed the API linked to in [1] at the API WG meeting. Overall it looks good, here’s a couple of pieces of feedback.</div>
<div><br>
</div>
<div>Update one App:</div>
<div>e.g. PATCH /apps/94cb7b89-0de8-492b-bf54-05ae96c9bd0e</div>
<div><br>
</div>
<div>We have a “Frozen” review (meaning it’s about to become a guideline) regarding that "Add section clarifying PUT vs PATCH semantics" [1]. Please give this a read and you can decide how to proceed. Comments on the review are certainly welcome too.</div>
<div><br>
</div>
<div>Fetch logs for last failed test action of one app:</div>
<div>GET /apps/2797a1f4-fc03-4c21-9dde-099cf7636ceb/logs?action=test&status=FAILED&limit=1</div>
<div><br>
</div>
<div>We have a guideline for Filtering [2]. Please read through it to see if it has any impact on your filtering. And note that we’re dropping the weird f_ prefix! [3]</div>
<div><br>
</div>
<div>If you have any follow up questions, you’re welcome to join us in #openstack-api or continue the conversation here.</div>
<div><br>
</div>
<div>Thanks,</div>
<div>Everett</div>
<div><br>
</div>
<div>[1] <a href="https://review.openstack.org/#/c/183945/5/guidelines/http.rst">
https://review.openstack.org/#/c/183945/5/guidelines/http.rst</a></div>
<div>[2] <a href="http://specs.openstack.org/openstack/api-wg/guidelines/pagination_filter_sort.html#filtering">http://specs.openstack.org/openstack/api-wg/guidelines/pagination_filter_sort.html#filtering</a></div>
<div>[3] <a href="https://review.openstack.org/#/c/198547/">https://review.openstack.org/#/c/198547/</a></div>
<div><br>
</div>
</div>
</body>
</html>