REST API query parameters
You can use query parameters to control what data is returned in endpoint responses.
This section applies to Open Storefront Framework (OSF) and Storefront Classic.
The sections below describe query parameters that you can use to control the set of items and properties in responses, and the order of the items returned.
Control the set of items returned
limit
query parameter to specify a different number. For example, the following call limits the number of orders returned to 5:GET /ccadmin/v1/orders?limit=5
offset
parameter. For example, suppose you have returned the first group of 250 orders using this call:GET /ccadmin/v1/orders
GET /ccadmin/v1/orders?offset=250
The default value of offset
is 0, which means the listing begins with the first item. So setting offset
to 250 means the listing begins with the 251st item.
limit
and offset
together. For example, to return the 401st through 600th order: GET /ccadmin/v1/orders?limit=200&offset=400
Control the set of properties returned
Another way to reduce the size of responses is to return only certain properties. For example, products can have a large number of properties, but you may need only certain ones.
fields
parameter to restrict the set of properties returned to only those you explicitly specify. The properties are specified as a comma-separated list. For example, to return only the id
and displayName
properties of products:GET /ccadmin/v1/products?fields=items.id,items.displayName
items
is the key for the array of objects returned, so top-level properties are referred to as items.propertyName
(for example, items.displayName
). Properties of nested objects are specified using additional period delimiters. For example:GET /ccadmin/v1/products?fields=items.listPrices.defaultPriceGroup
totalResults
, to return the total number of items available (such as the total number of products in the catalog). For example:GET /ccadmin/v1/products?fields=items.id,totalResults
Note that if a call does not use the fields
parameter, totalResults
is included in the response by default. For calls that use the fields parameter, totalResults
is suppressed unless it is explicitly listed as one of the fields to include.
As an alternative to the fields
parameter, which explicitly specifies the properties to include, you can use the exclude
parameter to include all properties except the ones specified. For example, to return all of the properties of products except longDescription
:
As with the fields
parameter, properties of nested objects can be specified for the exclude
parameter using additional period delimiters (for example, items.listPrices.defaultPriceGroup
).
If you use both the fields
and exclude
query parameters in the same request, the fields
parameter is applied first to determine the initial list of properties to return, and then the exclude
parameter is applied to remove properties from that list.
You can also create persistent response filters that store a list of the properties to include and the properties to exclude. See Response filters.
Control the order of items returned
By default, the items returned are sorted by a predetermined property that depends on the type of item. For example, products are sorted by displayName
.
sort
parameter to specify a different property to sort by. For example:GET /ccadmin/v1/products?sort=id
:asc
or :desc
to the property name to specify sorting in ascending or descending order. For example, to sort by id
descending:GET /ccadmin/v1/products?sort=id:desc
If you do not specify a sort order, it defaults to ascending.listPrice
, and then by displayName
(for items with identical listPrice
values):GET /ccadmin/v1/products?sort=listPrice,displayName
Note that sorting is done before applying limit
and offset
values, so it can affect not only the order in which items appear in the response, but also which items are returned. For example, if limit=200
and offset=400
, items 401 to 600 are selected from the sorted list of all items. If you change the sorting criteria, items 401 to 600 may not be the same ones as before.
Filter results
q
query parameter. This parameter is used for specifying a filter expression that restricts the set of the items returned, based on criteria such as numeric comparisons or string matching with the values of the items’ properties. For example, the following call returns only those products whose orderLimit
property has a value of less than 10:GET /ccadmin/v1/products?q=orderLimit lt 10
For most endpoints that support it, the q
parameter accepts filter expressions that use the syntax described in Section 3.2.2.2 of the System for Cross-Domain Identity Management (SCIM) specification, which is available at https://tools.ietf.org/html/draft-ietf-scim-api-12. A few endpoints accept filter expressions that use RQL syntax instead, as discussed below.
Use SCIM expressions for filtering
The SCIM specification defines standardized services for managing user identities in cloud environments. These services include a querying language for filtering the results returned by REST endpoints.
pa
:GET /ccadmin/v1/products?q=description sw "pa"
GET /ccadmin/v1/products?q=displayName co "shirt"
GET /ccadmin/v1/products?q=displayName CO "sHIrt"
Note that filter expressions must be URL encoded, so you must ensure that characters such as the quotation mark (") are escaped properly.AND
, OR
, and NOT
. For example, the following call returns products whose orderLimit
property has a value between 5 and 10:GET /ccadmin/v1/products?q=orderLimit gt 5 and orderLimit lt 10
Restrictions on filtering
- You can use only top-level properties of items in filter expressions. For example, for product endpoints, you cannot include properties of subobjects such as child SKUs.
- You can use a property in filter expressions only if it is returned by the endpoint you are calling. For example, if a specific product property is not returned by the
GET /ccadmin/v1/products
endpoint, then the property cannot be used with theq
parameter for that endpoint. Note, however, that equivalent endpoints in different APIs (for example,GET /ccadmin/v1/products
andGET /ccstore/v1/products
) may not return identical sets of properties, so a property that is not returned by one of these endpoints may be returned by the other.
Also, if you have multiple custom product types, and two or more custom types have a custom property with the same name, the property cannot be used in filter expressions. For example, if you have two custom product types called Shoes and Hats, and each has a custom property called material
, then you cannot use material
in filter expressions. If only one custom product type has a material
property, you can use the property in filter expressions.
Use RQL expressions for filtering
GET /ccadmin/v1/exchangerates
GET /ccadmin/v1/orders
GET /ccadmin/v1/posts
GET /ccadmin/v1/serverExtensions
GET /ccadmin/v1/webhookFailedMessages
You can find information about RQL syntax in the Oracle Commerce Platform documentation:
https://www.oracle.com/technetwork/indexes/documentation/atgwebcommerce-393465.html
See the Repository Query Language section of the Repository Guide.
GET /ccadmin/v1/exchangerates?q=exchangeRate > 3.5
GET /ccadmin/v1/webhookFailedMessages?q=savedTime=datetime("2018-9-22 12:05:54 GMT")
queryFormat
query parameter. For example:GET /ccadmin/v1/orders?queryFormat=SCIM&q=profileId eq "110658"