Re: REST API: Sorting, wish-list

Hi Ralf:

In message <[email protected]>,
Ralf Schlatterbeck writes:
>Sorting
>-------
>
>I noticed that we don't have sorting in the API. Similar to the
>@sort/@group syntax in the index urls I'd suggest a @sort property that
>gets a list of properties (similar to @fields) but with an optional
>prepended '-' to the property indicating reverse-sorting by that
>property?
>Example:
>@sort=creator,-creation
>would give us a list of issues sorted by creator and creation date,
>earlier dates last (reverse-sorted by creation date).

I am kind of ambivalent on sort. Unlike the web interface, where
javascript can be turned off, using the rest interface means that
javascript or some programming language (with a sort capability) is in
use.

It is probably more efficient to do on server side especially if
shoved into the database layer. The default order for collections is
based on the default hyperdb ordering IIRC:

   http://www.roundup-tracker.org/docs/customizing.html#setorderprop-property

I think using @sort=-field1,field2,-field3 is a good interface to use
when adding sort capabilities.

>Security
>--------
>
>I also noticed that the security checks for attributes seem to (always?)
>check the whole class, not individual properties. I think I can come up
>with a patch to fix this.


If this when retreiving fields using the
/rest/data/class?...&@fields=...  or when using /rest/data/class/id or
/rest/data/class/id/property?

>Limit
>-----
>
>Then I'd like to have a '@limit=number' (similar to SQL limit) clause
>that can limit the number of results returned (don't we already have
>something like this?). The idea is to return the biggest or smallest
>item (think dates) of something. So @sort + @limit=1 would get me this.
>Note that it would be a lot faster if this is handed down to SQL.

We have that.

  Collection endpoints support pagination. This is controlled by query
  parameters ``@page_size`` and ``@page_index`` (Note the use of the
  leading `@` to make the parameters distinguishable from field names.)

so you are looking for @page_size where @page_index (starting at 1)
determines the page of returned results.

ref: doc/rest.txt Pagination section

In your example, @page_size=1 should do the trick (@page_index is 1
so it starts with item 1 if not specified).


>Substring search
>----------------
>
>Currently strings do a substring-search. For an exact match we would
>have to extend the 'filter' method of the database. This is (at least
>for me) probably quite easy to do.
>
>How would we change the syntax of the REST queries?
>I'd suggest we change the semantics to do an exact match for
>property=string searches, that leave us with the question how substring
>search should be expressed.

I considered using property==string. But that looks to me like a
request for an exact match not a substring match. Maybe =~ (regexp
match operator in some languages). This does mean that searching for a
literal ~ at the front of the substring may be tricky leading to
text=~~rouilj for example.

Have a great day.

--
				-- rouilj
John Rouillard
===========================================================================
My employers don't acknowledge my existence much less my opinions.