All collections should be filterable using the same filter schema
All fields should be searchable
Lists of results should be sortable
It is expected that any field in an item is searchable via the collection. So if I have a resource/item with these parameters:
"agencyName": "Three Initial Corporation",
we should be able to filter based on things like
Note that JSON arrays (like the emailAddress) are accessed via arrayName.fieldName.
Note that query parameters are assumed to be case sensitive.
We should also be able to filter with substrings using a wildcard. Currently we use a single * at the end of the string to denote "substring and case insensitive."
So if I wanted to find all the people with a first name of something like Joe I could search
Which would return records with first names with the case-INsensitive substring "joe"
You should be able to filter any numeric field with one of three operators:
$eq: equal to
$gt: greater than
$lt: less than
So, to find records that were modified since Tue, 01 Nov 2016 00:23:12 GMT (or 1477959792), you would search on
To test for null or non-existent fields use the exists test for false
To return objects only when a value (any value) exists in the field, test for true:
The API should allow filtering on a list of values, for example, you hav three email addresses and want to return those three items:
By default the API returns 20 elements. size overrides the default number of elements; so if you want 100 items returned, do size=100 if you only want 1, do size=1
Pages start at 0. If a collection returns 100 items with 20 items per page, you would access the last page with page=4.
Denote which field to sort on, so if you wanted to sort by firstName you would do
Denotes which way to sort based on the fieldname in the sortBy parameter. So if you wanted Zaphod to come up at the top of the list an Arthur at the bottom you would do
The sort order should default to ascending based on the sortBy if not specified. If no sortBy is specified, no sortOrder is forced and data comes back in native storage results (e.g. however Mogno or SQL Server returns it by default). sortBy must be specified to for sortOrder to make sense.
Sorting on strings should be case insensitive. It makes a lot more sense for a consumer of the API to see:
Than the alternative:
If a consumer of the API wants to sort the response on more than one field, the sortBy and sortOrder need to be passed as comma separated fields. So, if for example, you want to sort people first by agencyCode and then by lastName you would pass
where the result would return groups by agencyCode sorted in ascending order with the people sorted descending by last name. By passing this as a comma separated string we are able to enforce which to sort on first.
Be sure to see my blog over at Cloudenity. This week's topic:
The Physical Impossibility of Migrating to the Cloud