[openstack-dev] [api][Solum] Request for feedback on new API resource

Everett Toews everett.toews at RACKSPACE.COM
Thu Jul 9 01:22:27 UTC 2015

On Jun 23, 2015, at 2:47 PM, Ed Cranford <ed.cranford at RACKSPACE.COM<mailto:ed.cranford at RACKSPACE.COM>> wrote:

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.

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.

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.

Thank you very much for your help.

[1] https://github.com/stackforge/solum-specs/blob/master/specs/liberty/app-resource.rst
[2] https://review.openstack.org/#/c/185147/ <https://review.openstack.org/#/c/185147/>

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.

Update one App:
e.g. PATCH /apps/94cb7b89-0de8-492b-bf54-05ae96c9bd0e

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.

Fetch logs for last failed test action of one app:
GET /apps/2797a1f4-fc03-4c21-9dde-099cf7636ceb/logs?action=test&status=FAILED&limit=1

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]

If you have any follow up questions, you’re welcome to join us in #openstack-api or continue the conversation here.


[1] https://review.openstack.org/#/c/183945/5/guidelines/http.rst
[2] http://specs.openstack.org/openstack/api-wg/guidelines/pagination_filter_sort.html#filtering
[3] https://review.openstack.org/#/c/198547/

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150709/ae9ff506/attachment.html>

More information about the OpenStack-dev mailing list