Re: [openstack-dev] [api] [glance] conclusion needed on functional API

2015-02-24 Thread michael mccune

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 

Re: [openstack-dev] [api] [glance] conclusion needed on functional API

2015-02-22 Thread Jay Pipes

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 ;)


Best,
-jay


[1] https://review.openstack.org/#/c/155911/

On 2/18/15, 4:49 PM, Miguel Grinberg miguel.s.grinb...@gmail.com
mailto:miguel.s.grinb...@gmail.com wrote:

Out of all the proposals mentioned in this thread, I think Jay's (d)
option is what is closer to the REST ideal:

d) POST /images/{image_id}/tasks with payload:
{ action: deactivate|activate }

Even though I don't think this is the perfect solution, I can
recognize that at least it tries to be RESTful, unlike the other
three options suggested in the first message.

That said, I'm going to keep insisting that in a REST API state
changes are the most important thing, and actions are implicitly
derived by the server from these state changes requested by the
client. What you are trying to do is to reverse this flow, you want
the client to invoke an action, which in turn will cause an implicit
state change on the server. This isn't wrong in itself, it's just
not the way you do REST.

Jay's (d) proposal above could be improved by making the task a real
resource. Sending a POST request to the /tasks address creates a new
task resource, which gets a URI of its own, returned in the Location
header. You can then send a GET request to this URI to obtain status
info, such as whether the task completed or not. And since tasks are
now real resources, they should have a documented representation as
well.

Miguel

On Wed, Feb 18, 2015 at 1:19 PM, Brian Rosmaita
brian.rosma...@rackspace.com mailto:brian.rosma...@rackspace.com
wrote:

On 2/15/15, 2:35 PM, Jay Pipes jaypi...@gmail.com
mailto:jaypi...@gmail.com wrote:
On 02/15/2015 01:13 PM, Brian Rosmaita wrote:
 On 2/15/15, 10:10 AM, Jay Pipes jaypi...@gmail.com 
mailto:jaypi...@gmail.com wrote:

 On 02/15/2015 01:31 AM, Brian Rosmaita wrote:
 This is a follow-up to the discussion at the 12 February API-WG
 meeting [1] concerning functional API in Glance [2].  We made
 some progress, but need to close this off so the spec can be
 implemented in Kilo.

 I believe this is where we left off: 1. The general consensus was
 that POST is the correct verb.

 Yes, POST is correct (though the resource is wrong).

 2. Did not agree on what to POST.  Three options are in play: (A)
 POST /images/{image_id}?action=deactivate POST
 /images/{image_id}?action=reactivate

 (B) POST /images/{image_id}/actions with payload describing the
 action, e.g., { action: deactivate } { action: reactivate
 }

 (C) POST 

Re: [openstack-dev] [api] [glance] conclusion needed on functional API

2015-02-18 Thread Brian Rosmaita
On 2/15/15, 2:35 PM, Jay Pipes jaypi...@gmail.com wrote:
On 02/15/2015 01:13 PM, Brian Rosmaita wrote:
 On 2/15/15, 10:10 AM, Jay Pipes jaypi...@gmail.com wrote:

 On 02/15/2015 01:31 AM, Brian Rosmaita wrote:
 This is a follow-up to the discussion at the 12 February API-WG
 meeting [1] concerning functional API in Glance [2].  We made
 some progress, but need to close this off so the spec can be
 implemented in Kilo.

 I believe this is where we left off: 1. The general consensus was
 that POST is the correct verb.

 Yes, POST is correct (though the resource is wrong).

 2. Did not agree on what to POST.  Three options are in play: (A)
 POST /images/{image_id}?action=deactivate POST
 /images/{image_id}?action=reactivate

 (B) POST /images/{image_id}/actions with payload describing the
 action, e.g., { action: deactivate } { action: reactivate
 }

 (C) POST /images/{image_id}/actions/deactivate POST
 /images/{image_id}/actions/reactivate

 d) POST /images/{image_id}/tasks with payload: { action:
 deactivate|activate }

 An action isn't created. An action is taken. A task is created. A
 task contains instructions on what action to take.

 The Images API v2 already has tasks (schema available at
 /v2/schemas/tasks ), which are used for long-running asynchronous
 operations (right now, image import and image export).  I think we
 want to keep those distinct from what we're talking about here.

 Does something really need to be created for this call?  The idea
 behind the functional API was to have a place for things that don't
 fit neatly into the CRUD-centric paradigm.  Option (C) seems like a
 good fit for this.

Why not just use the existing tasks/ interface, then? :) Seems like a
perfect fit to me.

The existing tasks/ interface is kind of heavyweight.  It provides a
framework for asynchronous operations.  It's really not appropriate for
this purpose.

cheers,
brian


__
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


Re: [openstack-dev] [api] [glance] conclusion needed on functional API

2015-02-18 Thread Miguel Grinberg
Out of all the proposals mentioned in this thread, I think Jay's (d) option
is what is closer to the REST ideal:

d) POST /images/{image_id}/tasks with payload:
   { action: deactivate|activate }

Even though I don't think this is the perfect solution, I can recognize
that at least it tries to be RESTful, unlike the other three options
suggested in the first message.

That said, I'm going to keep insisting that in a REST API state changes are
the most important thing, and actions are implicitly derived by the server
from these state changes requested by the client. What you are trying to do
is to reverse this flow, you want the client to invoke an action, which in
turn will cause an implicit state change on the server. This isn't wrong in
itself, it's just not the way you do REST.

Jay's (d) proposal above could be improved by making the task a real
resource. Sending a POST request to the /tasks address creates a new task
resource, which gets a URI of its own, returned in the Location header. You
can then send a GET request to this URI to obtain status info, such as
whether the task completed or not. And since tasks are now real resources,
they should have a documented representation as well.

Miguel

On Wed, Feb 18, 2015 at 1:19 PM, Brian Rosmaita 
brian.rosma...@rackspace.com wrote:

 On 2/15/15, 2:35 PM, Jay Pipes jaypi...@gmail.com wrote:
 On 02/15/2015 01:13 PM, Brian Rosmaita wrote:
  On 2/15/15, 10:10 AM, Jay Pipes jaypi...@gmail.com wrote:
 
  On 02/15/2015 01:31 AM, Brian Rosmaita wrote:
  This is a follow-up to the discussion at the 12 February API-WG
  meeting [1] concerning functional API in Glance [2].  We made
  some progress, but need to close this off so the spec can be
  implemented in Kilo.
 
  I believe this is where we left off: 1. The general consensus was
  that POST is the correct verb.
 
  Yes, POST is correct (though the resource is wrong).
 
  2. Did not agree on what to POST.  Three options are in play: (A)
  POST /images/{image_id}?action=deactivate POST
  /images/{image_id}?action=reactivate
 
  (B) POST /images/{image_id}/actions with payload describing the
  action, e.g., { action: deactivate } { action: reactivate
  }
 
  (C) POST /images/{image_id}/actions/deactivate POST
  /images/{image_id}/actions/reactivate
 
  d) POST /images/{image_id}/tasks with payload: { action:
  deactivate|activate }
 
  An action isn't created. An action is taken. A task is created. A
  task contains instructions on what action to take.
 
  The Images API v2 already has tasks (schema available at
  /v2/schemas/tasks ), which are used for long-running asynchronous
  operations (right now, image import and image export).  I think we
  want to keep those distinct from what we're talking about here.
 
  Does something really need to be created for this call?  The idea
  behind the functional API was to have a place for things that don't
  fit neatly into the CRUD-centric paradigm.  Option (C) seems like a
  good fit for this.
 
 Why not just use the existing tasks/ interface, then? :) Seems like a
 perfect fit to me.

 The existing tasks/ interface is kind of heavyweight.  It provides a
 framework for asynchronous operations.  It's really not appropriate for
 this purpose.

 cheers,
 brian


 __
 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

__
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


Re: [openstack-dev] [api] [glance] conclusion needed on functional API

2015-02-18 Thread Brian Rosmaita
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.

thanks,
brian

[1] https://review.openstack.org/#/c/155911/

On 2/18/15, 4:49 PM, Miguel Grinberg 
miguel.s.grinb...@gmail.commailto:miguel.s.grinb...@gmail.com wrote:
Out of all the proposals mentioned in this thread, I think Jay's (d) option is 
what is closer to the REST ideal:

d) POST /images/{image_id}/tasks with payload:
   { action: deactivate|activate }

Even though I don't think this is the perfect solution, I can recognize that at 
least it tries to be RESTful, unlike the other three options suggested in the 
first message.

That said, I'm going to keep insisting that in a REST API state changes are the 
most important thing, and actions are implicitly derived by the server from 
these state changes requested by the client. What you are trying to do is to 
reverse this flow, you want the client to invoke an action, which in turn will 
cause an implicit state change on the server. This isn't wrong in itself, it's 
just not the way you do REST.

Jay's (d) proposal above could be improved by making the task a real resource. 
Sending a POST request to the /tasks address creates a new task resource, which 
gets a URI of its own, returned in the Location header. You can then send a GET 
request to this URI to obtain status info, such as whether the task completed 
or not. And since tasks are now real resources, they should have a documented 
representation as well.

Miguel

On Wed, Feb 18, 2015 at 1:19 PM, Brian Rosmaita 
brian.rosma...@rackspace.commailto:brian.rosma...@rackspace.com wrote:
On 2/15/15, 2:35 PM, Jay Pipes 
jaypi...@gmail.commailto:jaypi...@gmail.com wrote:
On 02/15/2015 01:13 PM, Brian Rosmaita wrote:
 On 2/15/15, 10:10 AM, Jay Pipes 
 jaypi...@gmail.commailto:jaypi...@gmail.com wrote:

 On 02/15/2015 01:31 AM, Brian Rosmaita wrote:
 This is a follow-up to the discussion at the 12 February API-WG
 meeting [1] concerning functional API in Glance [2].  We made
 some progress, but need to close this off so the spec can be
 implemented in Kilo.

 I believe this is where we left off: 1. The general consensus was
 that POST is the correct verb.

 Yes, POST is correct (though the resource is wrong).

 2. Did not agree on what to POST.  Three options are in play: (A)
 POST /images/{image_id}?action=deactivate POST
 /images/{image_id}?action=reactivate

 (B) POST /images/{image_id}/actions with payload describing the
 action, e.g., { action: deactivate } { action: reactivate
 }

 (C) POST /images/{image_id}/actions/deactivate POST
 /images/{image_id}/actions/reactivate

 d) POST /images/{image_id}/tasks with payload: { action:
 deactivate|activate }

 An action isn't created. An action is taken. A task is created. A
 task contains instructions on what action to take.

 The Images API v2 already has tasks (schema available at
 /v2/schemas/tasks ), which are used for long-running asynchronous
 operations (right now, image import and image export).  I think we
 want to keep those distinct from what we're talking about here.

 Does something really need to be created for this call?  The idea
 behind the functional API was to have a place for things that don't
 fit neatly into the CRUD-centric paradigm.  Option (C) seems like a
 good fit for this.

Why not just use the existing tasks/ interface, then? :) Seems like a
perfect fit to me.

The existing tasks/ interface is kind of heavyweight.  It provides a
framework for asynchronous operations.  It's really not appropriate for
this purpose.

cheers,
brian


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

__
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


Re: [openstack-dev] [api] [glance] conclusion needed on functional API

2015-02-15 Thread Flavio Percoco

On 15/02/15 06:31 +, Brian Rosmaita wrote:

This is a follow-up to the discussion at the 12 February API-WG meeting
[1] concerning functional API in Glance [2].  We made some progress, but
need to close this off so the spec can be implemented in Kilo.

I believe this is where we left off:
1. The general consensus was that POST is the correct verb.

2. Did not agree on what to POST.  Three options are in play:
(A) POST /images/{image_id}?action=deactivate
   POST /images/{image_id}?action=reactivate

(B) POST /images/{image_id}/actions
   with payload describing the action, e.g.,
   { action: deactivate }
   { action: reactivate }

(C) POST /images/{image_id}/actions/deactivate
   POST /images/{image_id}/actions/reactivate

The spec proposes to use (C), following the discussion at the Atlanta
summit.

As a quick summary of why (C) was proposed (since all the above were
actually discussed at the summit), I'd like to quote from Hemanth's ML
posting right after the summit [4]:

1. Discoverability of operations.  It'll be easier to expose permitted
actions through schemas [or] a json home document living at
/images/{image_id}/actions/.
2. More conducive for rate-limiting. It'll be easier to rate-limit actions
in different ways if the action type is available in the URL.
3. Makes more sense for functional actions that don't require a request
body (e.g., image deactivation).


I like option C as well. It also leaves some room for sending
parameters in the body when the action requires it.

Thanks for the summary, Brian.
Flavio



If you have a strong opinion, please reply to this message, and I will
report on the conclusion at the API-WG meeting at 00:00 UTC on 2015-02-19
[5].  This will be the third API-WG meeting at which this topic was
discussed; I would really like to see us reach a conclusion at this
meeting.

Thank you!

[1]
http://eavesdrop.openstack.org/meetings/api_wg/2015/api_wg.2015-02-12-16.00
.log.html
[2] https://review.openstack.org/#/c/135122
[3]
https://etherpad.openstack.org/p/glance-adding-functional-operations-to-api
[4] http://lists.openstack.org/pipermail/openstack-dev/2014-May/036416.html
[5] https://wiki.openstack.org/wiki/Meetings/API-WG


__
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


--
@flaper87
Flavio Percoco


pgpjSAiiBxRsN.pgp
Description: PGP signature
__
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


Re: [openstack-dev] [api] [glance] conclusion needed on functional API

2015-02-15 Thread Jay Pipes

On 02/15/2015 01:31 AM, Brian Rosmaita wrote:

This is a follow-up to the discussion at the 12 February API-WG meeting
[1] concerning functional API in Glance [2].  We made some progress, but
need to close this off so the spec can be implemented in Kilo.

I believe this is where we left off:
1. The general consensus was that POST is the correct verb.


Yes, POST is correct (though the resource is wrong).


2. Did not agree on what to POST.  Three options are in play:
(A) POST /images/{image_id}?action=deactivate
 POST /images/{image_id}?action=reactivate

(B) POST /images/{image_id}/actions
 with payload describing the action, e.g.,
 { action: deactivate }
 { action: reactivate }

(C) POST /images/{image_id}/actions/deactivate
 POST /images/{image_id}/actions/reactivate


d) POST /images/{image_id}/tasks with payload:
   { action: deactivate|activate }

An action isn't created. An action is taken. A task is created. A task 
contains instructions on what action to take.


Best,
-jay


The spec proposes to use (C), following the discussion at the Atlanta
summit.

As a quick summary of why (C) was proposed (since all the above were
actually discussed at the summit), I'd like to quote from Hemanth's ML
posting right after the summit [4]:

1. Discoverability of operations.  It'll be easier to expose permitted
actions through schemas [or] a json home document living at
/images/{image_id}/actions/.
2. More conducive for rate-limiting. It'll be easier to rate-limit actions
in different ways if the action type is available in the URL.
3. Makes more sense for functional actions that don't require a request
body (e.g., image deactivation).

If you have a strong opinion, please reply to this message, and I will
report on the conclusion at the API-WG meeting at 00:00 UTC on 2015-02-19
[5].  This will be the third API-WG meeting at which this topic was
discussed; I would really like to see us reach a conclusion at this
meeting.

Thank you!

[1]
http://eavesdrop.openstack.org/meetings/api_wg/2015/api_wg.2015-02-12-16.00
.log.html
[2] https://review.openstack.org/#/c/135122
[3]
https://etherpad.openstack.org/p/glance-adding-functional-operations-to-api
[4] http://lists.openstack.org/pipermail/openstack-dev/2014-May/036416.html
[5] https://wiki.openstack.org/wiki/Meetings/API-WG


__
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



__
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


Re: [openstack-dev] [api] [glance] conclusion needed on functional API

2015-02-15 Thread Jay Pipes

On 02/15/2015 01:13 PM, Brian Rosmaita wrote:

On 2/15/15, 10:10 AM, Jay Pipes jaypi...@gmail.com wrote:


On 02/15/2015 01:31 AM, Brian Rosmaita wrote:

This is a follow-up to the discussion at the 12 February API-WG
meeting [1] concerning functional API in Glance [2].  We made
some progress, but need to close this off so the spec can be
implemented in Kilo.

I believe this is where we left off: 1. The general consensus was
that POST is the correct verb.


Yes, POST is correct (though the resource is wrong).


2. Did not agree on what to POST.  Three options are in play: (A)
POST /images/{image_id}?action=deactivate POST
/images/{image_id}?action=reactivate

(B) POST /images/{image_id}/actions with payload describing the
action, e.g., { action: deactivate } { action: reactivate
}

(C) POST /images/{image_id}/actions/deactivate POST
/images/{image_id}/actions/reactivate


d) POST /images/{image_id}/tasks with payload: { action:
deactivate|activate }

An action isn't created. An action is taken. A task is created. A
task contains instructions on what action to take.


The Images API v2 already has tasks (schema available at
/v2/schemas/tasks ), which are used for long-running asynchronous
operations (right now, image import and image export).  I think we
want to keep those distinct from what we're talking about here.

Does something really need to be created for this call?  The idea
behind the functional API was to have a place for things that don't
fit neatly into the CRUD-centric paradigm.  Option (C) seems like a
good fit for this.


Why not just use the existing tasks/ interface, then? :) Seems like a 
perfect fit to me.


Best,
-jay

__
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


Re: [openstack-dev] [api] [glance] conclusion needed on functional API

2015-02-15 Thread Brian Rosmaita
On 2/15/15, 10:10 AM, Jay Pipes jaypi...@gmail.com wrote:

On 02/15/2015 01:31 AM, Brian Rosmaita wrote:
 This is a follow-up to the discussion at the 12 February API-WG meeting
 [1] concerning functional API in Glance [2].  We made some progress,
but
 need to close this off so the spec can be implemented in Kilo.

 I believe this is where we left off:
 1. The general consensus was that POST is the correct verb.

Yes, POST is correct (though the resource is wrong).

 2. Did not agree on what to POST.  Three options are in play:
 (A) POST /images/{image_id}?action=deactivate
  POST /images/{image_id}?action=reactivate

 (B) POST /images/{image_id}/actions
  with payload describing the action, e.g.,
  { action: deactivate }
  { action: reactivate }

 (C) POST /images/{image_id}/actions/deactivate
  POST /images/{image_id}/actions/reactivate

d) POST /images/{image_id}/tasks with payload:
{ action: deactivate|activate }

An action isn't created. An action is taken. A task is created. A task
contains instructions on what action to take.

The Images API v2 already has tasks (schema available at /v2/schemas/tasks
), which are used for long-running asynchronous operations (right now,
image import and image export).  I think we want to keep those distinct
from what we're talking about here.

Does something really need to be created for this call?  The idea behind
the functional API was to have a place for things that don't fit neatly
into the CRUD-centric paradigm.  Option (C) seems like a good fit for this.

cheers,
brian

 



__
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


[openstack-dev] [api] [glance] conclusion needed on functional API

2015-02-14 Thread Brian Rosmaita
This is a follow-up to the discussion at the 12 February API-WG meeting
[1] concerning functional API in Glance [2].  We made some progress, but
need to close this off so the spec can be implemented in Kilo.

I believe this is where we left off:
1. The general consensus was that POST is the correct verb.

2. Did not agree on what to POST.  Three options are in play:
(A) POST /images/{image_id}?action=deactivate
POST /images/{image_id}?action=reactivate

(B) POST /images/{image_id}/actions
with payload describing the action, e.g.,
{ action: deactivate }
{ action: reactivate }

(C) POST /images/{image_id}/actions/deactivate
POST /images/{image_id}/actions/reactivate

The spec proposes to use (C), following the discussion at the Atlanta
summit.

As a quick summary of why (C) was proposed (since all the above were
actually discussed at the summit), I'd like to quote from Hemanth's ML
posting right after the summit [4]:

1. Discoverability of operations.  It'll be easier to expose permitted
actions through schemas [or] a json home document living at
/images/{image_id}/actions/.
2. More conducive for rate-limiting. It'll be easier to rate-limit actions
in different ways if the action type is available in the URL.
3. Makes more sense for functional actions that don't require a request
body (e.g., image deactivation).

If you have a strong opinion, please reply to this message, and I will
report on the conclusion at the API-WG meeting at 00:00 UTC on 2015-02-19
[5].  This will be the third API-WG meeting at which this topic was
discussed; I would really like to see us reach a conclusion at this
meeting.

Thank you!

[1] 
http://eavesdrop.openstack.org/meetings/api_wg/2015/api_wg.2015-02-12-16.00
.log.html
[2] https://review.openstack.org/#/c/135122
[3] 
https://etherpad.openstack.org/p/glance-adding-functional-operations-to-api
[4] http://lists.openstack.org/pipermail/openstack-dev/2014-May/036416.html
[5] https://wiki.openstack.org/wiki/Meetings/API-WG


__
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