Query parameters

Resource operations should use a consistent set of query parameters.

The following query parameters can be used in Resource operations. Sample values for the CustomersResource are listed as an example.

Figure 1. RADM and links to other models
This image shows the hierarchy of RADM model elements and how they link to other models.
This image shows the hierarchy of RADM model elements and how they link to other models.
Sorting
Sorting should be supported on relevant <<GET>> operations on Collection Resources and Member Resources.
Query Parameter Supported Parameter Values Notes
_sort +<field1>,+<field2>, Sort by specified fields in ascending order
-<field> Sort by specified fields in descending order
<field>{+sub_field1,-sub_field2} Sub-fields can be specified within { } with their own sort
Note:
  • The list of field names is a comma separated value list
  • Field names must match the name of the fields returned in the response
For example:
  • ../customers/123?_sort=name{+surname,+firstName},-created
Filtering
Filtering should be supported on relevant <<GET>> operations on Collection Resources and Member Resources.
Query Parameter Parameter Values Notes
_fields <field1>,<field2> Field names to include
<field1>,<field2>.<field3> Use ‚.’ notation to specify sub-fields to be filtered on.
<field1>,-<field2> use ‚-’ notation to specify fields not to be included.
_detail_level minimal Include the minimal set of fields
standard Include the standard set of fields
complete Include the complete set of fields
Note:
  • The list of field names is a comma separated value list
  • Field names must match the name of the fields returned in the response
For example:
  • ../customers/123?_fields=name.firstName,name.surname,dateOfBirth,address.postCode
  • ../customers/123?_fields=name,-address
  • ../customers/123?_detail_level=minimal
Searching
Searching should be supported on relevant <<GET>> operations on Collection Resources.
Query Alias Query Parameter Parameter Values Notes
<query alias> _<param name> <param values> Create a query alias for each required search on a resource collection. Specify the query parameters and parameter values to be used with each query alias.
Note: For example:
  • ../customers/external_reference?_ref=XYZ
Paging
Paging should be supported on <<GET>> operations on large Collection Resources.
Query Parameter Parameter Values Notes
_offset <number> The beginning item to return. Zero based.
_limit <number> Maximum number of items to return. Each service should set a default value and a maximum allowable value for _limit and document these.
Note: For example:
  • ../customers?_offset=0&_limit=50
  • ../customers?_offset=300&_limit=25
Expanding Resources

Expanding resources should be supported on relevant <<GET>> operations on Collection Resources and Member Resources (i.e. resources whose associated RDO is composed of other resource-linked RDOs).

Query Parameter Parameter Values Notes
_expand <resource1>,<resource2> Resource names to expand
Note:
  • The list of resource names is a comma separated value list
  • Resource names must match the name of the resources embedded in the response