Open Stack

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