Re: [openstack-dev] [api] [searchlight] Duplicate parameter names

[Chris Dent]

On Wed, 12 Oct 2016, McLellan, Steven wrote:


This issue came up during our meeting last week and it was suggested
to ask the API working group for its opinion, so any comments welcome.


If for whatever reason you don't get enough joy from the mailing
list, feel free to stick this topic on the agenda[1] and show up to
the meetings to talk about it. I'd hope in this case, however, that
email ought to suffice.


This obviously isn't life threatening, more of a convenience for a
number of people who's expressed frustration with getting the
parameter names wrong, but does anyone on the API WG have a strong
opinion against doing it?


If you've already established a commitment to elasticsearch and a
precedent for using some of its grammar for query strings I'd say
that _not_ doing it would be a mistake. What you've proposed in the
review (doing both but not allowing intermixing of the two styles).
makes sense to me.


[1] I am aware of the discussions around paging versus 'marker'-based
scrolling. We plan to add support for a more cursor-like method as
well, but Elasticsearch has always supported paging.


I think this is part of why the pagination guideline sort of stalled
out. In addition to the things you mentioned, it's also the case
that the concept of a page is broken in anything more than the
simplest environment.

I think in your case you want to go with what works and what users
will expect. That's the most important. Trying to achieve strict
consistency on query parameters across the entire breadth of
OpenStack isn't being considerate of the differents contexts of use
and users.

[1] https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda

--
Chris Dent   ┬─┬ノ( º _ ºノ)https://anticdent.org/
freenode: cdent tw: @anticdent__
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] [searchlight] Duplicate parameter names

[McLellan, Steven]

Hi,

This issue came up during our meeting last week and it was suggested to ask the 
API working group for its opinion, so any comments welcome.

Searchlight was born out of the Glance codebase, and so implemented "offset" 
and "limit" as paging parameters [1]. Where possible we've tried to map closely 
to Elasticsearch's API so that we don't have to translate parts of the query 
body into Elasticsearch's DSL (with the testing and documentation that comes 
along with it). Elasticsearch implements the same paging parameters as 'size' 
and 'from'.

Because at present we require an amount of knowledge of Elasticsearch's query 
language in order to use Searchlight, I proposed 
https://review.openstack.org/#/c/381956/ last week to add 'size' and 'from' as 
synonyms for 'offset' and 'limit' (and incidentally, we do plan to add a more 
scrolling/cursor-based method to work around the temporal problems with 
offset/limit). The two issues noted by folks:

* Having two parameters doing the same thing can be confusing (which in general 
I agree with though in this case I feel it's defensible)
* 'size' is ambiguous when it's part of a set of APIs as large as the Openstack 
community

This obviously isn't life threatening, more of a convenience for a number of 
people who's expressed frustration with getting the parameter names wrong, but 
does anyone on the API WG have a strong opinion against doing it?

Thanks!

Steve

[1] I am aware of the discussions around paging versus 'marker'-based 
scrolling. We plan to add support for a more cursor-like method as well, but 
Elasticsearch has always supported paging.
__
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