Re: [openstack-dev] [api] [glance] conclusion needed on functional API
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 recom
Re: [openstack-dev] [api] [glance] conclusion needed on functional API
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" 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
mailto:brian.rosma...@rackspace.com>>
wrote:
On 2/15/15, 2:35 PM, "Jay Pipes" mailto:jaypi...@gmail.com>> wrote:
>On 02/15/2015 01:13 PM, Brian Rosmaita wrote:
>> On 2/15/15, 10:10 AM, "Jay Pipes" 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 /images/{i
Re: [openstack-dev] [api] [glance] conclusion needed on functional API
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"
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
mailto:brian.rosma...@rackspace.com>> wrote:
On 2/15/15, 2:35 PM, "Jay Pipes"
mailto:jaypi...@gmail.com>> wrote:
>On 02/15/2015 01:13 PM, Brian Rosmaita wrote:
>> On 2/15/15, 10:10 AM, "Jay Pipes"
>> 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 /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
htt
Re: [openstack-dev] [api] [glance] conclusion needed on functional API
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" wrote:
> >On 02/15/2015 01:13 PM, Brian Rosmaita wrote:
> >> On 2/15/15, 10:10 AM, "Jay Pipes" 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
On 2/15/15, 2:35 PM, "Jay Pipes" wrote:
>On 02/15/2015 01:13 PM, Brian Rosmaita wrote:
>> On 2/15/15, 10:10 AM, "Jay Pipes" 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
On 02/15/2015 01:13 PM, Brian Rosmaita wrote:
On 2/15/15, 10:10 AM, "Jay Pipes" 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
On 2/15/15, 10:10 AM, "Jay Pipes" 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
Re: [openstack-dev] [api] [glance] conclusion needed on functional API
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
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
[openstack-dev] [api] [glance] conclusion needed on functional API
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
