REST API query parameters
You can use query parameters to control what data is returned in endpoint responses.
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"