2.11 Query Parameters
Collection URL parameters
The following table describes the query parameters that can be applied to URLs that return collections of resources (Atom feeds).
These parameters can be applied to URLs such as:
http://www.example.com/sdata/myApp/myContract/-/salesOrders
http://www.example.com/sdata/myApp/myContract/-/accounts('A001')/salesOrders
| Example | Description / Comments | Compliance |
|---|---|---|
| startIndex=21 | Paging: indicates the index of the first resource returned by the query. See Query Paging section for details. This index is 1-based (not 0-based). | MUST |
| count=10 | Paging: indicates the number of resources requested by the service consumer. The service may choose to return a different number of resources and it indicates this by setting the itemsPerPage element in the returned feed. See Query Paging section for details. | MUST |
| where=postalAddress.countryCode eq 'UK' | Specifies a filtering criteria. Only the resources that have a postal address in the UK are returned. See the Query Language section for details on how the where parameter is used. | MUST (with basic query level) |
| orderBy=postalAddress.countryCode asc,name desc | Specifies an ordering criteria. The collection is sorted first by ascending country code of their postal address, then by descending name. | MUST |
| search=wisteria | Specifies a full-text search criteria. The syntax for the search string may vary depending on the search engine used by the provider. SData does not attempt to introduce a standard syntax for full text searches because the search text is usually entered interactively through a search box. | MAY |
Collection and Resource URL parameters
The following table describes the query parameters that may be applied both to URLs that return collections of resources (Atom feeds) as well as URLs that return individual resources (Atom entries).
These parameters may be applied to URLs such as:
http://www.example.com/sdata/myApp/myContract/-/salesOrders?where=date.year ge 2008
http://www.example.com/sdata/myApp/myContract/-/salesOrders('S001')
| Examples | Description / Comments | Compliance |
|---|---|---|
| include=orderLines,customer include=$children include=$descriptors | Related orderLines and customer resources are returned together with the salesOrder resource(s). It is assumed only the sales order heading is returned by default. See Query Payload Control section for details. $children indicates the payload should include the resource and all its children resources (recursively). For example, a sales order with its order lines, its billing and delivery addresses, its associated notes. $descriptors indicates the payload should include "descriptors" for all related resources. The "descriptors" are human readable strings for the related resources. For example, first name + last name for a contact resource. The descriptors are carried by sdata:descriptor attributes in the payload. See Query Payload Control section for details. | MUST |
| precedence=2 | The resource's XML payload should only contain properties that have a precedence value <= 2 in the schema. See Property Definition section for details. If this parameter is set to 0, the payload should be completely omitted from the response. If this parameter is not set, the payload should contain all the properties listed in the schema, regardless of their priority value. This parameter allows the consumer to get a trimmed down version of the payload. This is useful when the consumer needs to fill a combo box for example. In this case, he can pass precedence=0 because he only needs an id/title pair for each entry and these can be obtained from the Atom entry. | MUST |
| select=id,orderDate,customer/id,billingAddres,deliveryAddress/* | Selects the properties that will be returned in the payload. This parameter allows a client to request that a specific list of properties be returned in the payload. It gives precise control over the breadth and depth of information returned. In the example, the payload will contain the order id, the order date, the customer id, the billing address (without any details) and the delivery address (with full details - but not recursive). The * character is the wildcard for all properties. This parameter shadows the include and precedence parameters. If include and/or precedence are specified in conjunction with select, the include and precedence values are ignored and only the select list is used. | MUST |
| includeSchema=true | The provider includes the feed or entry schema fragment in its response. See Inlined Schema section for details. | MAY |
Resource URL parameters
The following table describes the query parameters that may be applied to URLs that return individual resources (Atom entries).
These parameters may be applied to URLs such as:
http://www.example.com/sdata/myApp/myContract/-/salesOrders('S001')
| Examples | Description / Comments | Compliance |
|---|---|---|
| returnDelta=true | Indicates that the server should only include the properties that have been modified in its response. This parameter is only meaningful in POST and PUT requests. It is used to optimize the traffic and reduce the size of the payload returned by these operations. The SData provider may ignore this parameter and always return the entire payload. If the provider ignores this parameter, its consumers will not benefit from the traffic optimization but they should still function normally. | MAY |
POST parameters
The following table describes query parameters that only apply to POST operations. These parameters can be applied to URLs such as:
http://www.example.com/sdata/myApp/myContract/-/customers/$service/sendOverdueReminders
| Example | Description / Comments | Compliance |
|---|---|---|
| trackingID=abc42b0d-d110-4f5c-ac79-d3aa11bd20cb | Tracking id for reliable posting of asynchronous operations. See sections on reliable posting and asynchronous service operations for details on this parameter. | MAY |
Generic parameters
The following table describes the query parameters that can be applied to any SData URL, including schema URLs.
| Example | Description / Comments | Compliance |
|---|---|---|
| format=application/json | The resource(s) are returned in a specific format. Standardized MIME types are used to specify the format. A compliant SData service is only required to support the Atom format (feed and entry). Alternate formats is an optional feature that only some services honour. This parameter overrides any value passed through the HTTP Accept header | SHOULD |
| language=en-GB | Indicates the language the response must be in. This parameter overrides any value passed through the HTTP Accept-Language header. See localization section for details. | SHOULD |
| version=1.0.7 | Requests a specific version of the resource. See Resource Versioning section. This parameter is primarily used for schema URLs. The value of this parameter is a string and every application is free to choose its naming scheme for versions. But SData imposes the major.minor.revision format if the resource is a schema. See the 4.9 Schema Rules section for details. | MAY |
The compliance column indicates the level at which applications have to support these parameters. If a provider receives a parameter that it does not support or understand, it MUST ignore it. It MUST NOT return an error in this case.