On Jan 18, 2018, at 4:07 AM, TommyLike Hu <tommylik...@gmail.com> wrote:
> Recently We found an issue related to our OpenStack action APIs. We
> usually expose our OpenStack APIs by registering them to our API Gateway (for
> instance Kong [1]), but it becomes very difficult when regarding to action
> APIs. We can not register and control them seperately because them all share
> the same request url which will be used as the identity in the gateway
> service, not say rate limiting and other advanced gateway features, take a
> look at the basic resources in OpenStack
We discussed your email at today’s API-SIG meeting [0]. This is an area that is
always contentious in the RESTful world. Actions, tasks, and state changes are
not actual resources, and in a pure REST design they should never be part of
the URL. Instead, you should POST to the actual resource, with the desired
action in the body. So in your example:
> URL:/volumes/{volume_id}/action
> BODY:{'extend':{}}
the preferred way of achieving this is:
URL: POST /volumes/{volume_id}
BODY: {‘action’: ‘extend’, ‘params’: {}}
The handler for the POST action should inspect the body, and call the
appropriate method.
Having said that, we realize that a lot of OpenStack services have adopted the
more RPC-like approach that you’ve outlined. So while we strongly recommend a
standard RESTful approach, if you have already released an RPC-like API, our
advice is:
a) avoid having every possible verb in the URL. In other words, don’t use:
/volumes/{volume_id}/mount
/volumes/{volume_id}/umount
/volumes/{volume_id}/extend
This moves you further into RPC-land, and will make updating your API to a more
RESTful design more difficult.
b) choose a standard term for the item in the URL. In other words, always use
‘action’ or ‘task’ or whatever else you have adopted. Don’t mix terminology.
Then pass the action to perform, along with any parameters in the body. This
will make it easier to transition to a RESTful design by later updating the
handlers to first inspect the BODY instead of relying upon the URL to determine
what action to perform.
You might also want to contact the Kong developers to see if there is a way to
work with a RESTful API design.
-- Ed Leafe
[0]
http://eavesdrop.openstack.org/meetings/api_sig/2018/api_sig.2018-02-01-16.02.log.html#l-28
__________________________________________________________________________
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
