skip to main content
Structure of OData requests : Headers
 

Try DataDirect Cloud Now

Headers

You can use request headers to control the following service behaviors:
*Whether the response comes from cached data (if available) or from the back-end data store, as described in Refresh Result Header .
*Specify the backend data store credentials as described in Data Source User Header and Data Source Password Header.
*The time zone to apply to DateTime values, see Timezone Header.
*Anticipate how clients will be the $top system query parameter with the Top Mode to improve performance.
*How the service breaks up a result set into multiple responses with the OData Prefer Header - Max Page Size.
Some of these behaviors can be controlled with query parameters instead of in headers. See DataDirect Cloud custom query parameters.

Refresh Result Header

DataDirect Cloud buffers the results of an OData query, allowing clients to page back and forth through the results using the $top and $skip system query parameters. The $top parameter specifies how many results to return in the first response and $skip specifies where to start in the result set to return the next set of results. When the DataDirect Cloud service receives an OData query for which it has a buffered result and the $skip query parameter is either not specified or is set to zero, DataDirect Cloud can page back to the beginning of the buffered result or execute a new query.
By default, DataDirect Cloud treats a query where $skip is missing or set to zero as a request to re-execute the query in the backend data source. You can change default behavior in the Data Source definition, or in the request with the ddcloud-refresh-result header. The header value overrides the setting in the Refresh Result field of the Data Source definition.
Name
ddcloud-refresh-result
Accepted Values
0, reuse cached results. 1, discard cached results and query the data store again.
Default when not specified
1.The service executes the query anew.

Data Source User Header

The credentials for the backend data source can be stored in the Data Source definition on the General tab. If they are not, you must supply them in requests using the ddcloud-datasource-header header.
Name
ddcloud-datasource-user
Default when not specified
The DataDirect Cloud service checks the Data Source definition for this value.

Data Source Password Header

The credentials for the backend data source can be stored in the Data Source definition on the General tab. If they are not, you must supply them in requests using the ddcloud-datasource-password header.
Name
ddcloud-datasource-password
Default when not specified
The DataDirect Cloud service checks the Data Source definition for this value.

Timezone Header

To correctly process DateTime data types for clients in a different timezone than the data store, use the ddcloud-timezone header.
Name
ddcloud-timezone
Accepted Values
A Java timezone id string.
Default when not specified
The timezone is taken from URL; GMT is used if timezone is not specified as a header or URL parameter

Top Mode

In some cases, the DataDirect Cloud OData service can optimize requests to the backend data store when you use the ddcloud-top-mode to specify how a client will be using the $top system parameter to page through results. A value of 0 indicates that the client will use $top to limit the result set and will rarely request the remaining entities. A value of 1 indicates that the client will often use $top and $skip to page through results.
DataDirect Cloud only applies the optimization to queries that meet the following conditions:
*Include a value for $top
*Do not include $skip or include $skip with a value of 0
*Do not include $expand
*Do not include $inlinecount=allpages with the inline count mode set to 2, which causes a fetch of all rows
When the conditions are met, DataDirect Cloud will generate a SELECT statement that includes the data store-specific syntax for limiting the rows returned. If the client queries the same entity collection again but specifies $top and $skip to fetch more entities, the service executes a new query. The results might contain some of the entities already received from the first request.
In the following example, the ddcloud-top-mode is set to 1, directing the DataDirect Cloud service to fetch the complete result set and not to attempt optimization:
ddcloud-top-mode=1
Name
ddcloud-top-mode
Accepted Values
0 indicates that the client will use $top to limit the result set and will rarely request the remaining entities
1 indicates that the client will often use $top and $skip to page through results
Default when not specified
0

OData Prefer Header - Max Page Size

The OData 4.0 specification defines a Prefer header, odata.maxpagesize, that can be used to control the page size for server-driven paging. In server-driven paging, the server returns partial results and includes a link the client can use to get the next set of results. DataDirect Cloud supports the OData 2.0 standard, but uses the odata.maxpagesize Prefer header from the OData 4.0 specification to control the page size for server-driven paging.
You can set the page size in the Data Source definition, on the OData tab, in the Page Size field. The request header value for odata.maxpagesize overrides the value specified in the Data Source definition. In the following example, the maximum page size is set to 4000, resulting in up to 4000 entities per page.
Prefer: odata.maxpagesize=4000
Name
Prefer
Accepted Values
odata.maxpagesize=x where x is the maximum number of top-level entities that are returned on a page.
Default when not specified
The page size from either the data source or the service default page size.