Re: [openstack-dev] [api-wg] [api] [cinder] [nova] Support specify action name in request url

[Ed Leafe]

On Feb 2, 2018, at 2:11 AM, Duncan Thomas  wrote:
> 
> So I guess my question here is why is being RESTful good? Sure it's (very, 
> very loosely) a standard, but what are the actual advantages? Standards come 
> and go, what we want most of all is a good quality, easy to use API.

REST is HTTP. I don’t think that that is a “loose” standard by any measure.

> I'm not saying that going RESTful is wrong, but I don't see much discussion 
> about what the advantages are, only about how close we are to implementing it.

Here’s a quick summary of the advantages, courtesy of SO:

https://stackoverflow.com/questions/5320003/why-we-should-use-rest

REST is the standard for OpenStack APIs. Our job in the API-SIG is to help all 
projects develop their APIs to be as consistent as possible without using a 
top-down, heavy-handed approach. That’s why we included a suggestion for how to 
make your RPC-ish API consistent with other projects that also use an RPC-like 
approach to parts of their API.


-- Ed Leafe






__
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-wg] [api] [cinder] [nova] Support specify action name in request url

[Gilles Dubreuil]

As you said RESTful is not a standard but brings guidelines of good 
practices. Which in turn doesn't preclude adding ideas, as long as 
respecting RESTful approach. So we get from both sides.


Therefore a good schema structure adds to a de-facto standard, once the 
practice is commonly used.



On 02/02/18 19:11, Duncan Thomas wrote:
So I guess my question here is why is being RESTful good? Sure it's 
(very, very loosely) a standard, but what are the actual advantages? 
Standards come and go, what we want most of all is a good quality, 
easy to use API.


I'm not saying that going RESTful is wrong, but I don't see much 
discussion about what the advantages are, only about how close we are 
to implementing it.


On 1 Feb 2018 10:55 pm, "Ed Leafe" > wrote:


On Jan 18, 2018, at 4:07 AM, TommyLike Hu mailto: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




__
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-wg] [api] [cinder] [nova] Support specify action name in request url

[Duncan Thomas]

So I guess my question here is why is being RESTful good? Sure it's (very,
very loosely) a standard, but what are the actual advantages? Standards
come and go, what we want most of all is a good quality, easy to use API.

I'm not saying that going RESTful is wrong, but I don't see much discussion
about what the advantages are, only about how close we are to implementing
it.

On 1 Feb 2018 10:55 pm, "Ed Leafe"  wrote:

> On Jan 18, 2018, at 4:07 AM, TommyLike Hu  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
>
__
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-wg] [api] [cinder] [nova] Support specify action name in request url

[Ed Leafe]

On Jan 18, 2018, at 4:07 AM, TommyLike Hu  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

Re: [openstack-dev] [api-wg] [api] [cinder] [nova] Support specify action name in request url

[TommyLike Hu]

Thanks Hongbin, These links are useful for me!

Hongbin Lu 于2018年1月20日周六 上午3:20写道：

> I remembered there are several discussions about action APIs in the past.
> This is one discussion I can find:
> http://lists.openstack.org/pipermail/openstack-dev/2016-December/109136.html
> . An obvious alternative is to expose each action with an independent API
> endpoint. For example:
>
>
>
> * POST /servers//start:Start a server
>
> * POST /servers//stop:Stop a server
>
> * POST /servers//reboot:Reboot a server
>
> * POST /servers//pause:Pause a server
>
>
>
> Several people pointed out the pros and cons of either approach and other
> alternatives [1] [2] [3]. Eventually, we (OpenStack Zun team) have adopted
> the alternative approach [4] above and it works very well from my
> perspective. However, I understand that there is no consensus on this
> approach within the OpenStack community.
>
>
>
> [1]
> http://lists.openstack.org/pipermail/openstack-dev/2016-December/109178.html
>
> [2]
> http://lists.openstack.org/pipermail/openstack-dev/2016-December/109208.html
>
> [3]
> http://lists.openstack.org/pipermail/openstack-dev/2016-December/109248.html
>
> [4]
> https://developer.openstack.org/api-ref/application-container/#manage-containers
>
>
>
> Best regards,
>
> Hongbin
>
>
>
> *From:* TommyLike Hu [mailto:tommylik...@gmail.com]
> *Sent:* January-18-18 5:07 AM
> *To:* OpenStack Development Mailing List (not for usage questions) <
> openstack-dev@lists.openstack.org>
> *Subject:* [openstack-dev] [api-wg] [api] [cinder] [nova] Support specify
> action name in request url
>
>
>
> Hey all,
>
>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
>
>
>
>1. *Server*: "/servers/{server_id}/action"  35+ APIs are include.
>
>2. *Volume*: "/volumes/{volume_id}/action"  14 APIs are include.
>
>3. Other resource
>
>
>
> We have tried to register different interfaces with same upstream url,
> such as:
>
>
>
>   * api gateway*: /version/resource_one/action/action1 =>* upstream*:
> /version/resource_one/action
>
> *   api gateway*: /version/resource_one/action/action2 =>* upstream*:
> /version/resource_one/action
>
>
>
> But it's not secure enough cause we can pass action2 in the request body
> while invoking /action/action1, also, try to read the full body for route
> is not supported by most of the api gateways(maybe plugins) and will have a
> performance impact when proxy. So my question is do we have any solution or
> suggestion for this case? Could we support specify action name both in
> request body and url such as:
>
>
>
> *URL:/volumes/{volume_id}/action*
>
> *BODY:*{'extend':{}}
>
>
>
> and:
>
>
>
> *URL:/volumes/{volume_id}/action/extend*
>
> *BODY:* {'extend':{}}
>
>
>
> Thanks
>
> Tommy
>
>
>
> [1]: https://github.com/Kong/kong
> __
> 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-wg] [api] [cinder] [nova] Support specify action name in request url

[Hongbin Lu]

I remembered there are several discussions about action APIs in the past. This 
is one discussion I can find: 
http://lists.openstack.org/pipermail/openstack-dev/2016-December/109136.html . 
An obvious alternative is to expose each action with an independent API 
endpoint. For example:

* POST /servers//start:Start a server
* POST /servers//stop:Stop a server
* POST /servers//reboot:Reboot a server
* POST /servers//pause:Pause a server

Several people pointed out the pros and cons of either approach and other 
alternatives [1] [2] [3]. Eventually, we (OpenStack Zun team) have adopted the 
alternative approach [4] above and it works very well from my perspective. 
However, I understand that there is no consensus on this approach within the 
OpenStack community.

[1] http://lists.openstack.org/pipermail/openstack-dev/2016-December/109178.html
[2] http://lists.openstack.org/pipermail/openstack-dev/2016-December/109208.html
[3] http://lists.openstack.org/pipermail/openstack-dev/2016-December/109248.html
[4] 
https://developer.openstack.org/api-ref/application-container/#manage-containers

Best regards,
Hongbin

From: TommyLike Hu [mailto:tommylik...@gmail.com]
Sent: January-18-18 5:07 AM
To: OpenStack Development Mailing List (not for usage questions) 

Subject: [openstack-dev] [api-wg] [api] [cinder] [nova] Support specify action 
name in request url

Hey all,
   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

   1. Server: "/servers/{server_id}/action"  35+ APIs are include.
   2. Volume: "/volumes/{volume_id}/action"  14 APIs are include.
   3. Other resource

We have tried to register different interfaces with same upstream url, such as:

   api gateway: /version/resource_one/action/action1 => upstream: 
/version/resource_one/action
   api gateway: /version/resource_one/action/action2 => upstream: 
/version/resource_one/action

But it's not secure enough cause we can pass action2 in the request body while 
invoking /action/action1, also, try to read the full body for route is not 
supported by most of the api gateways(maybe plugins) and will have a 
performance impact when proxy. So my question is do we have any solution or 
suggestion for this case? Could we support specify action name both in request 
body and url such as:

URL:/volumes/{volume_id}/action
BODY:{'extend':{}}

and:

URL:/volumes/{volume_id}/action/extend
BODY: {'extend':{}}

Thanks
Tommy

[1]: https://github.com/Kong/kong
__
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