Open Stack

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