Modifiers
There are query parameters that can be appended to any of the endpoint URLs to modify the response. These modifiers apply mainly to list endpoints, and allow control of sorting, filtering, pagination, specifying which fields to return and the inclusion of related resources.
All modifiers can be combined in a single query to request exactly the desired data.
Pagination
Applies to: list endpoints
Use the page[size] parameter to change the number of items in a list, use page[number] to specify the page. The default page size is 30. Use page[size]=0 to disable pagination.
Examples
/models?page[size]=100
List of models, paginated per 100
/genes?page[size]=1000&page[number]=5
List of genes in default order, showing gene 4001 to 5000
Inclusion of related properties
Applies to: list and single endpoints
With the include query parameter, related resources can be included in a response. Provide a comma-separated list of relations to include.
In addition to the data, links, and jsonapi-fields of a normal response, an additional field 'included' is added to the response, which contains an array or related resources. The relationships-field in the data parameter of the main object(s) now includes a type and id parameter that refers to each item’s related resources. It is possible to include relations of related resources with the .-notation.
Note: included related resources do not benefit from pagination or other modifiers.
Examples
/models?include=files
List of models and include the files
/models/SIDM00003?include=sample.tissue
Include the sample and the sample's tissue for model SIDM00003
Sorting
Use the sort-parameter to change the sorting order of a list. Specify a comma-separated list on the fields to sort by. Default sorting is ascending, use a minus-sign (-) to sort descending on that field.
Sorting can be used on text-fields (alphabetically) or numerical fields, but not on properties of related properties.
Examples
/models/SIDM00003/datasets/genecnv?sort=-abs_copy_number,gistic_score
List all CNV for model SIDM00003, ordered descending by absolute copy number and then ascending by gistic score.
/samples?sort=sampling_year
List all samples sorted by sampling year.
Sparse Fieldsets
Applies to: single and list endpoints
Use the fields[resource] parameter to view a limited list of fields. Provide a comma separated list of fields to include. Selecting only the required fields can significantly reduce the size of the response and increase the speed.
Examples
/models?fields[model]=names
List all models, but only show the 'names'-property.
/models?include=sample.tissue&fields[sample]=id,tissue&fields[tissue]=name
List all models, include its sample and the samples tissue, but only include the tissue name.
Filtering
Applies to: list endpoints.
Filtering allows the list endpoint to be filtered on the server. Filtering is very powerful and flexible, but has a verbose syntax. The basic query parameter is as follows: filter=[list of filters]
A single filter in this list is a json object with three fields:{"name": <field to filter on>,"op": <operator for filtering>,"val": <value for filtering>}
The ‘name’ is the name of the attribute that is being filtered on.
The ‘op’ is the operator. There is a fixed list of valid operators, but availability depends on the field type of the field being filtered on:
Comperators
eq: check if field is equal to something
ne: check if field is not equal to something
gt: check if field is greater than to something
ge: check if field is greater than or equal to something
lt: check if field is less than to something
le: check if field is less than or equal to something
contains: check if field contains a string
like: check if field contains a string
notlike: check if field does not contains a string
ilike: check if field contains a string (case insensitive)
notilike: check if field does not contains a string (case insensitive)
startswith: check if field starts with a string
endswith: check if field ends with a string
in_: check if field is in a list of values
notin_: check if field is not in a list of values
any: used to filter on to many relationships
has: used to filter on to one relationships
Multiple filters can be applied with the 'and', 'or' and 'not' logic combinators.