Open Stack

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/


________________________________
From: Everett Toews <everett.toews at RACKSPACE.COM>
Sent: Tuesday, June 23, 2015 8:58 AM
To: OpenStack Development Mailing List (not for usage questions)
Subject: Re: [openstack-dev] [api][Solum] Request for feedback on new API resource

On Jun 18, 2015, at 3:07 PM, Devdatta Kulkarni <devdatta.kulkarni at RACKSPACE.COM<mailto:devdatta.kulkarni at RACKSPACE.COM>> wrote:

Hi, API WG team,

In Solum, recently we have been working on some changes to our REST API.

Basically, we have introduced a new resource ('app'). The spec for this has been accepted by Solum cores.
https://github.com/stackforge/solum-specs/blob/master/specs/liberty/app-resource.rst

Right now we have a patch for review implementing this spec:
https://review.openstack.org/#/c/185147/

If it is not too much to request, I was wondering if someone from your team can take a look
at the spec and the review, to see if we are not violating any of your guidelines.

Thank you for your help.

- Devdatta

Do you have this API documented anywhere?

Is there a spec or similar for this API change?

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].

Regards,
Everett

[1] https://review.openstack.org/#/c/177397/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150623/49d989c4/attachment-0001.html>