<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<style type="text/css" style="display:none"><!--P{margin-top:0;margin-bottom:0;} --></style>
</head>
<body dir="ltr" style="font-size:12pt;color:#000000;background-color:#FFFFFF;font-family:Calibri,Arial,Helvetica,sans-serif;">
<p>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>
</p>
<p><br>
</p>
<p>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.
<br>
</p>
<p><br>
</p>
<p>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.</p>
<p><br>
</p>
<p>Thank you very much for your help.</p>
<p><br>
</p>
<p>[1] <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></p>
<p>[2] <a href="https://review.openstack.org/#/c/185147/
">https://review.openstack.org/#/c/185147/
</a><br>
</p>
<p><br>
</p>
<div style="word-wrap:break-word">
<hr tabindex="-1" style="display:inline-block; width:98%">
<div id="divRplyFwdMsg" dir="ltr"><font style="font-size:11pt" face="Calibri, sans-serif" color="#000000"><b>From:</b> Everett Toews <everett.toews@RACKSPACE.COM><br>
<b>Sent:</b> Tuesday, June 23, 2015 8:58 AM<br>
<b>To:</b> OpenStack Development Mailing List (not for usage questions)<br>
<b>Subject:</b> Re: [openstack-dev] [api][Solum] Request for feedback on new API resource</font>
<div> </div>
</div>
<div>
<div>
<div>
<div>On Jun 18, 2015, at 3:07 PM, Devdatta Kulkarni <<a href="mailto:devdatta.kulkarni@RACKSPACE.COM">devdatta.kulkarni@RACKSPACE.COM</a>> wrote:</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; 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">Hi, API WG team,</div>
<div style="margin-top:0px; margin-bottom:0px"><br>
</div>
<div style="margin-top:0px; margin-bottom:0px">In Solum, recently we have been working on some changes to our REST API.</div>
<div style="margin-top:0px; margin-bottom:0px"><br>
</div>
<div style="margin-top:0px; margin-bottom:0px">Basically, we have introduced a new resource ('app'). The spec for this has been accepted by Solum cores.<br>
</div>
<div style="margin-top:0px; margin-bottom:0px"><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"><br>
</div>
<div style="margin-top:0px; margin-bottom:0px">Right now we have a patch for review implementing this spec:</div>
<div style="margin-top:0px; margin-bottom:0px"><a href="https://review.openstack.org/#/c/185147/">https://review.openstack.org/#/c/185147/</a></div>
<div style="margin-top:0px; margin-bottom:0px"><br>
</div>
<div style="margin-top:0px; margin-bottom:0px">If it is not too much to request, I was wondering if someone from your team can take a look</div>
<div style="margin-top:0px; margin-bottom:0px">at the spec and the review, to see if we are not violating any of your guidelines.</div>
<div style="margin-top:0px; margin-bottom:0px"><br>
</div>
<div style="margin-top:0px; margin-bottom:0px">Thank you for your help.</div>
<div style="margin-top:0px; margin-bottom:0px"><br>
</div>
<div style="margin-top:0px; margin-bottom:0px">- Devdatta<br>
</div>
</div>
</blockquote>
<div><br>
</div>
<div>Do you have this API documented anywhere?</div>
<div><br>
</div>
<div>Is there a spec or similar for this API change?</div>
<div><br>
</div>
<div>In our experience, it’s best to consider the API design apart from the implementation. The separation of concerns makes for a cleaner review and a better design. The Glance team did a good job of this in their Artifact Repository API specification [1].</div>
<div><br>
</div>
<div>Regards,</div>
<div>Everett</div>
<div><br>
</div>
<div>[1] <a href="https://review.openstack.org/#/c/177397/">https://review.openstack.org/#/c/177397/</a></div>
</div>
</div>
</div>
</div>
</body>
</html>