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: [email protected]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
