Re: [openstack-dev] [Glance][TC] Glance Functional API and Cross-project API Consistency

[Jay Pipes]

On 06/11/2014 02:34 AM, Mark Washenberger wrote:

I think the tasks stuff is something different, though. A task is a
(potentially) long-running operation. So it would be possible for an
action to result in the creation of a task. As the proposal stands
today, the actions we've been looking at are an alternative to the
document-oriented PATCH HTTP verb. There was nearly unanimous consensus
that we found "POST /resources/actions/verb {inputs to verb}" to be a
more expressive and intuitive way of accomplishing some workflows than
trying to use JSON-PATCH documents.


Why do tasks necessarily mean the operation is long-running? As 
mentioned before to Brian R, just have the deactivation action be a 
task. There's no need to create a new faux-resource called 'action', IMO...


Best,
-jay


On Tue, Jun 10, 2014 at 4:15 PM, Jay Pipes mailto:jaypi...@gmail.com>> wrote:

On Wed, Jun 4, 2014 at 11:54 AM, Sean Dague mailto:s...@dague.net>> wrote:

On 05/30/2014 02:22 PM, Hemanth Makkapati wrote:
 > Hello All,
 > I'm writing to notify you of the approach the Glance
community has
 > decided to take for doing functional API.  Also, I'm writing
to solicit
 > your feedback on this approach in the light of cross-project API
 > consistency.
 >
 > At the Atlanta Summit, the Glance team has discussed introducing
 > functional API in Glance so as to be able to expose
operations/actions
 > that do not naturally fit into the CRUD-style. A few
approaches are
 > proposed and discussed here
 >

.
 > We have all converged on the approach to include 'action' and
action
 > type in the URL. For instance, 'POST
 > /images/{image_id}/actions/{action_type}'.
 >
 > However, this is different from the way Nova does actions.
Nova includes
 > action type in the payload. For instance, 'POST
 > /servers/{server_id}/action {"type": "", ...}'.
At this
 > point, we hit a cross-project API consistency issue mentioned
here
 >


 > (under the heading 'How to act on resource - cloud perform on
 > resources'). Though we are differing from the way Nova does
actions and
 > hence another source of cross-project API inconsistency , we
have a few
 > reasons to believe that Glance's way is helpful in certain ways.
 >
 > The reasons are as following:
 > 1. Discoverability of operations.  It'll be easier to expose
permitted
 > actions through schemas 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).
 >
 > At this point we are curious to see if the API conventions group
 > believes this is a valid and reasonable approach.
 > Any feedback is much appreciated. Thank you!

Honestly, I like POST /images/{image_id}/actions/{action_type} much
better than ACTION being embedded in the body (the way nova
currently
does it), for the simple reason of reading request logs:


I agree that not including the action type in the POST body is much
nicer and easier to read in logs, etc.

That said, I prefer to have resources actually be things that the
software creates. An action isn't created. It is performed.

I would prefer to replace the term "action(s)" with the term
"task(s)", as is proposed for Nova [1].

Then, I'd be happy as a pig in, well, you know.

Best,
-jay

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

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org

http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev




___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [Glance][TC] Glance Functional API and Cross-project API Consistency

[Jay Pipes]

On 06/11/2014 12:25 AM, Brian Rosmaita wrote:

 > That said, I prefer to have resources actually be things that the
software creates. An action
 > isn't created. It is performed.
 >
 > I would prefer to replace the term "action(s)" with the term
"task(s)", as is proposed for Nova [1].

Glance already uses "tasks" in the v2 URL for creating resources that
represent long-running asynchronous processes (import, export, cloning),
so that terminology is already taken.  (The documentation is lagging a
bit behind the code on tasks, though.)

The aim here is to introduce something that doesn't fit cleanly into a
CRUD-centric view.  For example, a cloud provider may need to put an
imported (or otherwise problematic) image into "deactivated" status
while the image is being investigated for some malicious stuff built
into it [2].


So just have a task that does deactivation... there's no need to create 
this new "action" resource IMO.



 Image status, however, is never set directly by users or
admins; image status transitions are handled entirely by Glance.  (You
don't delete an image by updating its status to be 'deleted'; rather,
its status becomes 'deleted' as a result of a DELETE request).  Using an
Images v2 PATCH call in this context would be misleading because we're
not modifying the image's status--we can't.  We're asking Glance to take
an action with respect to an image, the result of which will be that the
image will be deactivated (or reactivated), and Glance will modify the
image's status accordingly.

cheers,
brian

[1] https://review.openstack.org/#/c/86938/
[2] https://wiki.openstack.org/wiki/Glance-deactivate-image

*From:* Jay Pipes [jaypi...@gmail.com]
*Sent:* Tuesday, June 10, 2014 7:15 PM
*To:* OpenStack Development Mailing List (not for usage questions)
*Subject:* Re: [openstack-dev] [Glance][TC] Glance Functional API and
Cross-project API Consistency

On Wed, Jun 4, 2014 at 11:54 AM, Sean Dague mailto:s...@dague.net>> wrote:

On 05/30/2014 02:22 PM, Hemanth Makkapati wrote:
 > Hello All,
 > I'm writing to notify you of the approach the Glance community has
 > decided to take for doing functional API.  Also, I'm writing to
solicit
 > your feedback on this approach in the light of cross-project API
 > consistency.
 >
 > At the Atlanta Summit, the Glance team has discussed introducing
 > functional API in Glance so as to be able to expose
operations/actions
 > that do not naturally fit into the CRUD-style. A few approaches are
 > proposed and discussed here
 >

<https://etherpad.openstack.org/p/glance-adding-functional-operations-to-api>.
 > We have all converged on the approach to include 'action' and action
 > type in the URL. For instance, 'POST
 > /images/{image_id}/actions/{action_type}'.
 >
 > However, this is different from the way Nova does actions. Nova
includes
 > action type in the payload. For instance, 'POST
 > /servers/{server_id}/action {"type": "", ...}'. At this
 > point, we hit a cross-project API consistency issue mentioned here
 >

<https://etherpad.openstack.org/p/juno-cross-project-consistency-across-rest-apis>
 > (under the heading 'How to act on resource - cloud perform on
 > resources'). Though we are differing from the way Nova does
actions and
 > hence another source of cross-project API inconsistency , we have
a few
 > reasons to believe that Glance's way is helpful in certain ways.
 >
 > The reasons are as following:
 > 1. Discoverability of operations.  It'll be easier to expose
permitted
 > actions through schemas 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).
 >
 > At this point we are curious to see if the API conventions group
 > believes this is a valid and reasonable approach.
 > Any feedback is much appreciated. Thank you!

Honestly, I like POST /images/{image_id}/actions/{action_type} much
better than ACTION being embedded in the body (the way nova currently
does it), for the simple reason of reading request logs:


I agree that not including the action type in the POST body is much
nicer and easier to read in logs, etc.

That said, I prefer to have resources actually be things that th

Re: [openstack-dev] [Glance][TC] Glance Functional API and Cross-project API Consistency

[Mark Washenberger]

I think the tasks stuff is something different, though. A task is a
(potentially) long-running operation. So it would be possible for an action
to result in the creation of a task. As the proposal stands today, the
actions we've been looking at are an alternative to the document-oriented
PATCH HTTP verb. There was nearly unanimous consensus that we found "POST
/resources/actions/verb {inputs to verb}" to be a more expressive and
intuitive way of accomplishing some workflows than trying to use JSON-PATCH
documents.


On Tue, Jun 10, 2014 at 4:15 PM, Jay Pipes  wrote:

> On Wed, Jun 4, 2014 at 11:54 AM, Sean Dague  wrote:
>
>> On 05/30/2014 02:22 PM, Hemanth Makkapati wrote:
>> > Hello All,
>> > I'm writing to notify you of the approach the Glance community has
>> > decided to take for doing functional API.  Also, I'm writing to solicit
>> > your feedback on this approach in the light of cross-project API
>> > consistency.
>> >
>> > At the Atlanta Summit, the Glance team has discussed introducing
>> > functional API in Glance so as to be able to expose operations/actions
>> > that do not naturally fit into the CRUD-style. A few approaches are
>> > proposed and discussed here
>> > <
>> https://etherpad.openstack.org/p/glance-adding-functional-operations-to-api
>> >.
>> > We have all converged on the approach to include 'action' and action
>> > type in the URL. For instance, 'POST
>> > /images/{image_id}/actions/{action_type}'.
>> >
>> > However, this is different from the way Nova does actions. Nova includes
>> > action type in the payload. For instance, 'POST
>> > /servers/{server_id}/action {"type": "", ...}'. At this
>> > point, we hit a cross-project API consistency issue mentioned here
>> > <
>> https://etherpad.openstack.org/p/juno-cross-project-consistency-across-rest-apis
>> >
>> > (under the heading 'How to act on resource - cloud perform on
>> > resources'). Though we are differing from the way Nova does actions and
>> > hence another source of cross-project API inconsistency , we have a few
>> > reasons to believe that Glance's way is helpful in certain ways.
>> >
>> > The reasons are as following:
>> > 1. Discoverability of operations.  It'll be easier to expose permitted
>> > actions through schemas 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).
>> >
>> > At this point we are curious to see if the API conventions group
>> > believes this is a valid and reasonable approach.
>> > Any feedback is much appreciated. Thank you!
>>
>> Honestly, I like POST /images/{image_id}/actions/{action_type} much
>> better than ACTION being embedded in the body (the way nova currently
>> does it), for the simple reason of reading request logs:
>>
>
> I agree that not including the action type in the POST body is much nicer
> and easier to read in logs, etc.
>
> That said, I prefer to have resources actually be things that the software
> creates. An action isn't created. It is performed.
>
> I would prefer to replace the term "action(s)" with the term "task(s)", as
> is proposed for Nova [1].
>
> Then, I'd be happy as a pig in, well, you know.
>
> Best,
> -jay
>
> [1] https://review.openstack.org/#/c/86938/
>
> ___
> OpenStack-dev mailing list
> OpenStack-dev@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [Glance][TC] Glance Functional API and Cross-project API Consistency

[Brian Rosmaita]

> That said, I prefer to have resources actually be things that the software 
> creates. An action
> isn't created. It is performed.
>
> I would prefer to replace the term "action(s)" with the term "task(s)", as is 
> proposed for Nova [1].

Glance already uses "tasks" in the v2 URL for creating resources that represent 
long-running asynchronous processes (import, export, cloning), so that 
terminology is already taken.  (The documentation is lagging a bit behind the 
code on tasks, though.)

The aim here is to introduce something that doesn't fit cleanly into a 
CRUD-centric view.  For example, a cloud provider may need to put an imported 
(or otherwise problematic) image into "deactivated" status while the image is 
being investigated for some malicious stuff built into it [2].  Image status, 
however, is never set directly by users or admins; image status transitions are 
handled entirely by Glance.  (You don't delete an image by updating its status 
to be 'deleted'; rather, its status becomes 'deleted' as a result of a DELETE 
request).  Using an Images v2 PATCH call in this context would be misleading 
because we're not modifying the image's status--we can't.  We're asking Glance 
to take an action with respect to an image, the result of which will be that 
the image will be deactivated (or reactivated), and Glance will modify the 
image's status accordingly.

cheers,
brian

[1] https://review.openstack.org/#/c/86938/
[2] https://wiki.openstack.org/wiki/Glance-deactivate-image

From: Jay Pipes [jaypi...@gmail.com]
Sent: Tuesday, June 10, 2014 7:15 PM
To: OpenStack Development Mailing List (not for usage questions)
Subject: Re: [openstack-dev] [Glance][TC] Glance Functional API and 
Cross-project API Consistency

On Wed, Jun 4, 2014 at 11:54 AM, Sean Dague 
mailto:s...@dague.net>> wrote:
On 05/30/2014 02:22 PM, Hemanth Makkapati wrote:
> Hello All,
> I'm writing to notify you of the approach the Glance community has
> decided to take for doing functional API.  Also, I'm writing to solicit
> your feedback on this approach in the light of cross-project API
> consistency.
>
> At the Atlanta Summit, the Glance team has discussed introducing
> functional API in Glance so as to be able to expose operations/actions
> that do not naturally fit into the CRUD-style. A few approaches are
> proposed and discussed here
> <https://etherpad.openstack.org/p/glance-adding-functional-operations-to-api>.
> We have all converged on the approach to include 'action' and action
> type in the URL. For instance, 'POST
> /images/{image_id}/actions/{action_type}'.
>
> However, this is different from the way Nova does actions. Nova includes
> action type in the payload. For instance, 'POST
> /servers/{server_id}/action {"type": "", ...}'. At this
> point, we hit a cross-project API consistency issue mentioned here
> <https://etherpad.openstack.org/p/juno-cross-project-consistency-across-rest-apis>
> (under the heading 'How to act on resource - cloud perform on
> resources'). Though we are differing from the way Nova does actions and
> hence another source of cross-project API inconsistency , we have a few
> reasons to believe that Glance's way is helpful in certain ways.
>
> The reasons are as following:
> 1. Discoverability of operations.  It'll be easier to expose permitted
> actions through schemas 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).
>
> At this point we are curious to see if the API conventions group
> believes this is a valid and reasonable approach.
> Any feedback is much appreciated. Thank you!

Honestly, I like POST /images/{image_id}/actions/{action_type} much
better than ACTION being embedded in the body (the way nova currently
does it), for the simple reason of reading request logs:

I agree that not including the action type in the POST body is much nicer and 
easier to read in logs, etc.

That said, I prefer to have resources actually be things that the software 
creates. An action isn't created. It is performed.

I would prefer to replace the term "action(s)" with the term "task(s)", as is 
proposed for Nova [1].

Then, I'd be happy as a pig in, well, you know.

Best,
-jay

[1] https://review.openstack.org/#/c/86938/
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [Glance][TC] Glance Functional API and Cross-project API Consistency

[Christopher Yeoh]

On Wed, Jun 11, 2014 at 8:45 AM, Jay Pipes  wrote:

> On Wed, Jun 4, 2014 at 11:54 AM, Sean Dague  wrote:
>
>> On 05/30/2014 02:22 PM, Hemanth Makkapati wrote:
>> > Hello All,
>> > I'm writing to notify you of the approach the Glance community has
>> > decided to take for doing functional API.  Also, I'm writing to solicit
>> > your feedback on this approach in the light of cross-project API
>> > consistency.
>> >
>> > At the Atlanta Summit, the Glance team has discussed introducing
>> > functional API in Glance so as to be able to expose operations/actions
>> > that do not naturally fit into the CRUD-style. A few approaches are
>> > proposed and discussed here
>> > <
>> https://etherpad.openstack.org/p/glance-adding-functional-operations-to-api
>> >.
>> > We have all converged on the approach to include 'action' and action
>> > type in the URL. For instance, 'POST
>> > /images/{image_id}/actions/{action_type}'.
>> >
>> > However, this is different from the way Nova does actions. Nova includes
>> > action type in the payload. For instance, 'POST
>> > /servers/{server_id}/action {"type": "", ...}'. At this
>> > point, we hit a cross-project API consistency issue mentioned here
>> > <
>> https://etherpad.openstack.org/p/juno-cross-project-consistency-across-rest-apis
>> >
>> > (under the heading 'How to act on resource - cloud perform on
>> > resources'). Though we are differing from the way Nova does actions and
>> > hence another source of cross-project API inconsistency , we have a few
>> > reasons to believe that Glance's way is helpful in certain ways.
>> >
>> > The reasons are as following:
>> > 1. Discoverability of operations.  It'll be easier to expose permitted
>> > actions through schemas 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).
>> >
>> > At this point we are curious to see if the API conventions group
>> > believes this is a valid and reasonable approach.
>> > Any feedback is much appreciated. Thank you!
>>
>> Honestly, I like POST /images/{image_id}/actions/{action_type} much
>> better than ACTION being embedded in the body (the way nova currently
>> does it), for the simple reason of reading request logs:
>>
>
> I agree that not including the action type in the POST body is much nicer
> and easier to read in logs, etc.
>
> That said, I prefer to have resources actually be things that the software
> creates. An action isn't created. It is performed.
>
>
So that depends a bit on whether the action can be performed immediately or
not. Sometimes presumably it can?

I would prefer to replace the term "action(s)" with the term "task(s)", as
> is proposed for Nova [1].
>
>
I agree It'd probably be worth other projects looking at the proposed tasks
API for Nova for long running tasks. Better that the infra
for it be put in now and return task handles than have to try to retrofit
something later on.

As for the earlier question about whether Nova should try to follow this
proposal. IMO I think Nova should, but its something we'd converge to
over the long term (presumably using a microversion bump).

Regards,

Chris
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [Glance][TC] Glance Functional API and Cross-project API Consistency

[Jay Pipes]

On Wed, Jun 4, 2014 at 11:54 AM, Sean Dague  wrote:

> On 05/30/2014 02:22 PM, Hemanth Makkapati wrote:
> > Hello All,
> > I'm writing to notify you of the approach the Glance community has
> > decided to take for doing functional API.  Also, I'm writing to solicit
> > your feedback on this approach in the light of cross-project API
> > consistency.
> >
> > At the Atlanta Summit, the Glance team has discussed introducing
> > functional API in Glance so as to be able to expose operations/actions
> > that do not naturally fit into the CRUD-style. A few approaches are
> > proposed and discussed here
> > <
> https://etherpad.openstack.org/p/glance-adding-functional-operations-to-api
> >.
> > We have all converged on the approach to include 'action' and action
> > type in the URL. For instance, 'POST
> > /images/{image_id}/actions/{action_type}'.
> >
> > However, this is different from the way Nova does actions. Nova includes
> > action type in the payload. For instance, 'POST
> > /servers/{server_id}/action {"type": "", ...}'. At this
> > point, we hit a cross-project API consistency issue mentioned here
> > <
> https://etherpad.openstack.org/p/juno-cross-project-consistency-across-rest-apis
> >
> > (under the heading 'How to act on resource - cloud perform on
> > resources'). Though we are differing from the way Nova does actions and
> > hence another source of cross-project API inconsistency , we have a few
> > reasons to believe that Glance's way is helpful in certain ways.
> >
> > The reasons are as following:
> > 1. Discoverability of operations.  It'll be easier to expose permitted
> > actions through schemas 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).
> >
> > At this point we are curious to see if the API conventions group
> > believes this is a valid and reasonable approach.
> > Any feedback is much appreciated. Thank you!
>
> Honestly, I like POST /images/{image_id}/actions/{action_type} much
> better than ACTION being embedded in the body (the way nova currently
> does it), for the simple reason of reading request logs:
>

I agree that not including the action type in the POST body is much nicer
and easier to read in logs, etc.

That said, I prefer to have resources actually be things that the software
creates. An action isn't created. It is performed.

I would prefer to replace the term "action(s)" with the term "task(s)", as
is proposed for Nova [1].

Then, I'd be happy as a pig in, well, you know.

Best,
-jay

[1] https://review.openstack.org/#/c/86938/
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [Glance][TC] Glance Functional API and Cross-project API Consistency

[Mark McLoughlin]

On Fri, 2014-05-30 at 18:22 +, Hemanth Makkapati wrote:
> Hello All,
> I'm writing to notify you of the approach the Glance community has
> decided to take for doing functional API.  Also, I'm writing to
> solicit your feedback on this approach in the light of cross-project
> API consistency.
> 
> At the Atlanta Summit, the Glance team has discussed introducing
> functional API in Glance so as to be able to expose operations/actions
> that do not naturally fit into the CRUD-style. A few approaches are
> proposed and discussed here. We have all converged on the approach to
> include 'action' and action type in the URL. For instance,
> 'POST /images/{image_id}/actions/{action_type}'.
> 
> However, this is different from the way Nova does actions. Nova
> includes action type in the payload. For instance,
> 'POST /servers/{server_id}/action {"type": "", ...}'. At
> this point, we hit a cross-project API consistency issue mentioned
> here (under the heading 'How to act on resource - cloud perform on
> resources'). Though we are differing from the way Nova does actions
> and hence another source of cross-project API inconsistency , we have
> a few reasons to believe that Glance's way is helpful in certain ways.
> 
> The reasons are as following:
> 1. Discoverability of operations.  It'll be easier to expose permitted
> actions through schemas 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).
> 
> At this point we are curious to see if the API conventions group
> believes this is a valid and reasonable approach.

It's obviously preferable if new APIs follow conventions established by
existing APIs, but I think you've laid out pretty compelling rationale
for not following Nova's lead on this.

The question is whether Nova should plan on adopting this approach in a
future version of its API?

Mark.



___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [Glance][TC] Glance Functional API and Cross-project API Consistency

[Mark Washenberger]

I will provide a little more context for the TC audience. I asked Hemanth
to tag this message [TC] because at the Juno summit in the cross-project
track there was discussion of cross-project api consistency [1]. The main
outcome of that meeting was that "TC should recommend API conventions via
openstack/governance as defined by those interested in the community". If
you dig further into that etherpad, I believe there is a writeup of
"actions" but I don't think we actually found time to hit that point during
the discussion.

Thanks!


[1] -
https://etherpad.openstack.org/p/juno-cross-project-consistency-across-rest-apis


On Fri, May 30, 2014 at 11:22 AM, Hemanth Makkapati <
hemanth.makkap...@rackspace.com> wrote:

>  Hello All,
> I'm writing to notify you of the approach the Glance community has decided
> to take for doing functional API.  Also, I'm writing to solicit your
> feedback on this approach in the light of cross-project API consistency.
>
> At the Atlanta Summit, the Glance team has discussed introducing
> functional API in Glance so as to be able to expose operations/actions that
> do not naturally fit into the CRUD-style. A few approaches are proposed and
> discussed here
> .
> We have all converged on the approach to include 'action' and action type
> in the URL. For instance, 'POST /images/{image_id}/actions/{action_type}'.
>
> However, this is different from the way Nova does actions. Nova includes
> action type in the payload. For instance, 'POST /servers/{server_id}/action
> {"type": "", ...}'. At this point, we hit a cross-project API
> consistency issue mentioned here
> 
> (under the heading 'How to act on resource - cloud perform on resources').
> Though we are differing from the way Nova does actions and hence another
> source of cross-project API inconsistency , we have a few reasons to
> believe that Glance's way is helpful in certain ways.
>
>
> The reasons are as following:
> 1. Discoverability of operations.  It'll be easier to expose permitted
> actions through schemas 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).
>
> At this point we are curious to see if the API conventions group believes
> this is a valid and reasonable approach.
>
> Any feedback is much appreciated. Thank you!
>
> Regards,
> Hemanth Makkapati
>
> ___
> OpenStack-dev mailing list
> OpenStack-dev@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [Glance][TC] Glance Functional API and Cross-project API Consistency

[Sean Dague]

On 05/30/2014 02:22 PM, Hemanth Makkapati wrote:
> Hello All,
> I'm writing to notify you of the approach the Glance community has
> decided to take for doing functional API.  Also, I'm writing to solicit
> your feedback on this approach in the light of cross-project API
> consistency.
> 
> At the Atlanta Summit, the Glance team has discussed introducing
> functional API in Glance so as to be able to expose operations/actions
> that do not naturally fit into the CRUD-style. A few approaches are
> proposed and discussed here
> .
> We have all converged on the approach to include 'action' and action
> type in the URL. For instance, 'POST
> /images/{image_id}/actions/{action_type}'.
> 
> However, this is different from the way Nova does actions. Nova includes
> action type in the payload. For instance, 'POST
> /servers/{server_id}/action {"type": "", ...}'. At this
> point, we hit a cross-project API consistency issue mentioned here
> 
> (under the heading 'How to act on resource - cloud perform on
> resources'). Though we are differing from the way Nova does actions and
> hence another source of cross-project API inconsistency , we have a few
> reasons to believe that Glance's way is helpful in certain ways.
> 
> The reasons are as following:
> 1. Discoverability of operations.  It'll be easier to expose permitted
> actions through schemas 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).
> 
> At this point we are curious to see if the API conventions group
> believes this is a valid and reasonable approach.
> Any feedback is much appreciated. Thank you!

Honestly, I like POST /images/{image_id}/actions/{action_type} much
better than ACTION being embedded in the body (the way nova currently
does it), for the simple reason of reading request logs:

http://logs.openstack.org/55/97755/2/check/check-tempest-dsvm-full/02b01ba/logs/screen-n-api.txt.gz?level=INFO#_2014-06-04_14_51_55_960

-Sean

-- 
Sean Dague
http://dague.net



signature.asc
Description: OpenPGP digital signature
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [Glance][TC] Glance Functional API and Cross-project API Consistency

[Zhi Yan Liu]

Hello Hemanth,

Thanks for your summary, and raise it up in ML.

All of them are sensible to me, there is only one concern from
implementation perspective for me like to get folks notice.

If we follow 'POST /images/{image_id}/actions/{action_type}' approach,
I think we will hard to write common code on wsgi handling level (just
like current Nova approach did [0]) and keep router code be clear
(e.g. [1]) - don't need to add different rule to mapper for different
function/action be case by case. Rather, this way is straightforward
and I agreed those three reasons are understandable, but TBH probably
we need to think about it from implementation perspective a little
bit, follow this way we need to write more duplicated code for each
function/action on different code place/layer, e.g. [2] for route
layer. And for rate-limiting requirement, if we go 'POST
/servers/{server_id}/action {"type": "", ...}' way,
probably we can do the limiting on wsgi/common layer easily as well,
of course we could design it later base on the selection.

[0] 
https://github.com/openstack/nova/blob/master/nova/api/openstack/wsgi.py#L1053
[1] 
https://github.com/openstack/nova/blob/master/nova/api/openstack/compute/contrib/server_start_stop.py#L43
[2] https://github.com/openstack/glance/blob/master/glance/api/v2/router.py#L81

zhiyan

On Sat, May 31, 2014 at 2:22 AM, Hemanth Makkapati
 wrote:
> Hello All,
> I'm writing to notify you of the approach the Glance community has decided
> to take for doing functional API.  Also, I'm writing to solicit your
> feedback on this approach in the light of cross-project API consistency.
>
> At the Atlanta Summit, the Glance team has discussed introducing functional
> API in Glance so as to be able to expose operations/actions that do not
> naturally fit into the CRUD-style. A few approaches are proposed and
> discussed here. We have all converged on the approach to include 'action'
> and action type in the URL. For instance, 'POST
> /images/{image_id}/actions/{action_type}'.
>
> However, this is different from the way Nova does actions. Nova includes
> action type in the payload. For instance, 'POST /servers/{server_id}/action
> {"type": "", ...}'. At this point, we hit a cross-project API
> consistency issue mentioned here (under the heading 'How to act on resource
> - cloud perform on resources'). Though we are differing from the way Nova
> does actions and hence another source of cross-project API inconsistency ,
> we have a few reasons to believe that Glance's way is helpful in certain
> ways.
>
> The reasons are as following:
> 1. Discoverability of operations.  It'll be easier to expose permitted
> actions through schemas 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).
>
> At this point we are curious to see if the API conventions group believes
> this is a valid and reasonable approach.
> Any feedback is much appreciated. Thank you!
>
> Regards,
> Hemanth Makkapati
>
> ___
> OpenStack-dev mailing list
> OpenStack-dev@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

[openstack-dev] [Glance][TC] Glance Functional API and Cross-project API Consistency

[Hemanth Makkapati]

Hello All,
I'm writing to notify you of the approach the Glance community has decided to 
take for doing functional API.  Also, I'm writing to solicit your feedback on 
this approach in the light of cross-project API consistency.

At the Atlanta Summit, the Glance team has discussed introducing functional API 
in Glance so as to be able to expose operations/actions that do not naturally 
fit into the CRUD-style. A few approaches are proposed and discussed 
here.
 We have all converged on the approach to include 'action' and action type in 
the URL. For instance, 'POST /images/{image_id}/actions/{action_type}'.

However, this is different from the way Nova does actions. Nova includes action 
type in the payload. For instance, 'POST /servers/{server_id}/action {"type": 
"", ...}'. At this point, we hit a cross-project API consistency 
issue mentioned 
here
 (under the heading 'How to act on resource - cloud perform on resources'). 
Though we are differing from the way Nova does actions and hence another source 
of cross-project API inconsistency , we have a few reasons to believe that 
Glance's way is helpful in certain ways.

The reasons are as following:
1. Discoverability of operations.  It'll be easier to expose permitted actions 
through schemas 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).

At this point we are curious to see if the API conventions group believes this 
is a valid and reasonable approach.
Any feedback is much appreciated. Thank you!

Regards,
Hemanth Makkapati
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev