Request Parameters

This section will walk you though all the automatically configured request parameters and their use cases.

Filters

Some endpoints return information describing a single identified item but many return information on a list of items. Such list endpoints support query parameters to filter the list to only include some items. In most cases these filters take the form:

prop1.prop2...propn=value

Here, the props are the short property names that appear in the JSON format and the value is the value that the property is required to have. The value might be a number, a string, a date or a URI. In the case of the URI then you can often use the last segment of the URI on its own. If the same filter is used twice with different values then the API will return results for both values (i.e. it acts as a disjunction).

You can apply prefixes to the parameter in order to apply standard filters to your query:

An example would be min-dob=12/03/1993 to query resources with date of birth after 12/03/1993.

You are also allowed to set a range filter using parenthesis, i.e. ( and ) for setting an exclusive bound and (* and *) to sent an inclusive bound. Make sure to separate values with .. . Be aware that you can also mix and match the boundaries having one inclusive and one exclusive. For example friends=(4..17*) which will match all resources that have more than 4 friends and less than or equal to 17.

You can also filter based on whether the resource has any values for a given property path. Set the value of the exists-{path} query parameter to true to include only items which have one or more values for that path, or false to include only items which have no value.

Text Search

You can also filter query results by specifying text fragments to search for in the data. This feature uses Apache Lucene to perform a text search on certain fields, determined by the API and the database configuration. Use the search query parameter to specify the text fragments to search for. If multiple terms are given, each term can be separated by a space, ^ or %, and only results whose text contains all of the terms will be returned.

You can use the wildcard character * in a text fragment.

Search Modifiers

You can customise your search request by supplying additional query parameters with the search parameter.

The fuzzy and raw-search parameters are simply flags which will be evaluated based on whether they are present on the request.

Text Search Path

You can request a text search on related resources by supplying a search-{path} parameter instead of the usual search parameter. The path should be a .-separated property path from the root resource of the request to the related resources, which will be treated as the subject of the text search.

This approach may be useful in cases where the root resources returned by the endpoint don’t have any text-indexed properties, but their related resources do. It is only available when the endpoint has defined views.

A text search path can be used in conjunction with the usual search modifiers.

Examples

View Modification Parameters

List endpoints also support view modification parameters. These are distinguished by starting with an underscore character. The commonly supported modifiers are:

If a limit or offset is applicable, whether explicit in the query or implicitly imposed by the API, then the metadata object will include a limit or offset field to show what limits were applied.

Aggregate Query Parameters

List endpoints support aggregate query parameters, _count and _groupBy. You can use these to request a summarised view of the data that would normally be returned by that endpoint.

Each parameter takes similar values, in the form of dot-separated view paths (eg. friend.name), or the root path @id. You can specify each parameter multiple times to perform any number of aggregations and groupings.

When aggregation parameters are supplied, parameters which alter the view of the results (eg. _projection, _view) will not be applied. However, parameters which alter the result set, such as filters, can be applied in conjunction.

Example

To count the total number of records in a list:

/path?_count=@id

JSON response:

items: [{
  "count": 142
}]

To count the number of children of each record:

/path?_groupBy=@id&_count=incomingConnection

JSON response:

items: [{
  "@id": "http://training.epimorphics.com/transport/london-underground/station/upney",
  "incomingConnection.count": 2
}, {
  ...
}]

Note

The soft record limit that is defined by the endpoint does not apply to aggregate requests, so they may consume more resources than similar requests to the same endpoint. You can mitigate this by supplying a _limit query parameter.

Note

This feature currently supports the JSON and CSV result formats. Other formats are available but are experimental and should not be relied upon.

Aliases

Each endpoint can configure a mapping of parameter aliases to the names of the parameters they represent. You can set this by setting the aliases property on the endpoint spec. This allows users to send the aliased parameters either in their original form, or using an alias. This may be useful for shortening the names of commonly used filter parameters, for example.

Quick Reference