On 02/24/2015 03:09 AM, Flavio Percoco wrote:
On 22/02/15 22:43 -0500, Jay Pipes wrote:
On 02/18/2015 06:37 PM, Brian Rosmaita wrote:
Thanks for your comment, Miguel.  Your suggestion is indeed very close
to the RESTful ideal.

However, I have a question for the entire API-WG.  Our (proposed)
mission is "To improve the developer experience of API users by
converging the OpenStack API to a consistent and pragmatic RESTful
design." [1]  My question is: what is the sense of "pragmatic" in this
sentence?  I thought it meant that we advise the designers of OpenStack
APIs to adhere to RESTful design as much as possible, but allow them to
diverge where appropriate.  The proposed functional call to deactivate
an image seems to be an appropriate place to deviate from the ideal.
 Creating a task or action object so that the POST request will create
a new resource does not seem very pragmatic.  I believe that a necessary
component of encouraging OpenStack APIs to be consistent is to allow
some pragmatism.

Hi Brian,

I'm sure you're not surprised by my lack of enthusiasm for the
"functional" Glance API spec for activating/deactivating an image :)

As for the role of the API WG in this kind of thing, you're absolutely
correct that the goal of the WG is to improve the developer experience
of API users with a consistent and pragmatic RESTful design.

I feel the proposed `PUT /images/{image_id}/actions/deactivate` is
neither consistent (though to be fair, the things this would be
"consistent" with in the Nova API -- i.e. the os-actions API -- are
monstrosities IMHO) nor pragmatic.

This kind of thing, IMHO, is not something that belongs in the same
REST API as the other Glance image API calls. It's purely an
administrative thing and belongs in a separate API, and doesn't even
need to be RESTful. The glance-manage command would be more
appropriate, with direct calls to backend database systems to flip the
status to activate/deactivate.

If this functionality really does need to be in the main user RESTful
API, I believe it should follow the existing v2 Glance API's /tasks
resource model for consistency and design reasons.

That said, I'm only one little voice on the API WG. Happy to hear
other's views on this topic and go with the majority's view (after
arguing for my points of course ;)


many thanks to Jay and Miguel, i think you guys are spot on in terms of the most RESTful way to solve this issue. i voted to support the "C" option but, given the arguments, i can see the wisdom of "D".

i think the idea of pragmatism and best practices really comes into intersection with this issue. it seems that the most ideal solution would be for glance to extend their tasks resource to allow this activate|deactivate functionality. but it seemed like this approach was non-ideal given the state of the project and the plans for future development.

this is partially why i felt a little weird voting on what we think glance should do. mainly because there are really good ideas about how this could be solved in the most ideal RESTful fashion. but, those suggestions might lead to a large amount of work that will only delay the requested feature.


I've been hacking on the "task side" of Glance lately and I believe
this could actually be implemented. Something we definitely need to
figure out before this happens is whether we can make some tasks run
in a serial engine while others run in a "workers-based" one, for
example.

I believe there are tasks we don't want to delegate to other nodes
because they don't do anything that is "heavy" compute-wise.

The benefit I see from doing this using tasks is that we don't
introduce yet-another-endpoint and it gives us more flexibility from a
maintenance perspective. It'd be a matter of adding a new task to
Glance and register it.

However, the CLI implementation for tasks is P.A.I.N.F.U.L.L and it
requires you to write json in the terminal. This can defeinitely be
improved, though.


this response from Flavio really drives home the point for me concerning our recommendations to projects, unintended consequences, and pragmatic convergence on best practices. there are many details that we do not have visibility on, and this just indicates that we need to be fully involved with the projects we advise (duh). we should definitely be creating guidelines that are the best practices and designs available, but i think we should also make some effort to help show others the path from where they are currently to where we think they should be. which, arguably, is what we are doing =)

i think this issue is a great example of a situation where we have ideas about a most RESTful solution that happens to intersect poorly with the current state of the project. it makes me wonder about how we will provide guidance for a project that wants to move towards a better API while making incremental steps.

in this case we are creating dissonance with respect to convergence. we are recommending a path forward that will help to achieve the stated goal, but in doing so we are introducing a pattern that will make backward compatibility difficult should the project move towards the "tasks" solution. i think in this respect Jay's comments about a separate API make a great deal of sense.

i'm unsure that there is an easy or clear solution to the notion of differences between our recommendations and a path towards convergence, but i think it's worth discussing more. i think it would be worthwhile to generate some sort of checklist or workflow to help inform projects of the longer term implications of convergence (as we define it). this might give developers pause for thought when designing features that have API impact.


mike

__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Reply via email to