Open Stack

Yes, the query parameters I'm talking about are on GET requests – mostly list resources calls – where you use the query parameters to filter the results.

For example, list servers, list flavors, list images…..

There aren't a lot of them – is anyone opposed to me showing the query parameters in the URIs?



Diane
----------------------------------------------
Diane Fleming
Software Developer II - US
diane.fleming at rackspace.com
Cell  512.323.6799
Office 512.874.1260
Skype drfleming0227
Google-plus diane.fleming at gmail.com

From: Nick Chase <nchase at mirantis.com<mailto:nchase at mirantis.com>>
Date: Wednesday, July 10, 2013 12:24 PM
To: Diane Fleming <diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com>>
Cc: "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>>
Subject: Re: [Openstack-docs] Hi all - question

In general, it's unusual to include parameters on POST request URLs.  That's not to say that it can't be done, but I think it might be a bit confusing; even if the parameters are sent on the URL, they ALSO have to be sent as part of the reqeust body, as a normal POST request.

That said, I'd be all for identifying "query" parameters in the tables...

----  Nick


On Wed, Jul 10, 2013 at 11:16 AM, Diane Fleming <diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com>> wrote:
No, I'm not suggesting that, though that's a good idea.  I'm suggesting that the calls that have query parameters show them, like this

GET /<URL>/servers?marker=marker&limit=limit

Sent from my iPhone

On Jul 10, 2013, at 7:57 AM, "Nick Chase" <nchase at mirantis.com<mailto:nchase at mirantis.com>> wrote:

On Wed, Jul 10, 2013 at 8:32 AM, Diane Fleming <diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com>> wrote:

For example, in the individual API references, they do appear in the URIs, like this:

http://docs.openstack.org/api/openstack-compute/2/content/List_Servers-d1e2078.html

However, this same call on the API Reference page looks like this – (see the "List Ids, names, and links for all servers" call)

http://api.openstack.org/api-ref.html#compute

The query parms are described in the table, but don't appear in the URI itself. I find this really confusing. I'd like to have the page changed so that these appear in the URI – what are your thoughts? At the very least, they should be identified as "query" parameters in the table. Let me know your thoughts!

That URL actually refers to many calls, though; Are you suggesting that each call should have its own anchor, such as:

http://api.openstack.org/api-ref.html#compute_servers_list
http://api.openstack.org/api-ref.html#compute_servers_create
http://api.openstack.org/api-ref.html#compute_servers_detail
http://api.openstack.org/api-ref.html#compute_servers_delete

I'd be for that.

----  Nick




-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20130710/66edc7de/attachment.html>