Skip to main content
Version: Next

$timeout

Functionality

Definition

The $timeout endpoint defines the number of seconds to save an entity set in the server's cache. This parameter works in conjunction with $method=entityset to control the lifespan of the cached entity set.

Syntax

To set a timeout for an entity set, use the following format:

GET /rest/{{dataClass}}?$filter="{{filterExpression}}"&$method=entityset&?$timeout={{seconds}}
tip

The $timeout endpoint accepts a numerical value representing the number of seconds the entity set should remain in the cache. For example, 1800 seconds for 30 minutes.

Detailed Behavior

Default Timeout

By default, the timeout is set to two (2) hours.

Using the $timeout Parameter

When an entity set is created with a specified timeout, the following occurs:

  • The entity set is stored in the cache for the defined number of seconds.

  • Each time the entity set is accessed, the timeout is recalculated from the current time.

  • If the entity set is recreated using $savedfilter, the new default timeout is 10 minutes.

Using Specific Formats

To set different timeout durations for an entity set, adjust the number of seconds in the $timeout parameter.

Combining with $expand

The $timeout parameter can be used alongside $expand to manage the lifespan of expanded entity sets. Ensure that the $expand parameter is properly defined to retrieve related entities within the specified timeout period.

Combining with Other Parameters

The $timeout parameter can be combined with other parameters:

  • $expand: Retrieve related entities within the specified timeout period.

  • $filter: Define specific criteria for the entities included in the entity set.

  • $orderby: Sort the entities in the entity set.

  • $top/$limit: Limit the number of entities returned in the entity set.

  • $skip: Skip a specified number of entities in the result set.

  • $savedfilter and $savedorderby: Save the filter and order by criteria to recreate the entity set with the same reference ID.

Use Cases

Setting a Custom Timeout

Request:

To create an entity set that expires after 20 minutes:

GET /rest/Employee?$filter="salary>50000"&$method=entityset&$timeout=1200

Response:

{
"__ENTITYSET": "/rest/Employee/$entityset/3BA2B71499244F60A38CD51E11ACDDF8",
"__DATACLASS": "Employee",
"__entityModel": "Employee",
"__GlobalStamp": 0,
"__COUNT": 50,
"__SENT": 50,
"__ENTITIES": [ ... ],
"__FIRST": 0
}

Default Timeout Behavior

If no $timeout parameter is specified, the default timeout of 2 hours is applied:

Request:

GET /rest/Employee?$filter="department='HR'"&$method=entityset

Response:

{
"__ENTITYSET": "/rest/Employee/$entityset/3BA2B71499244F60A38CD51E11ACDDF8",
"__DATACLASS": "Employee",
"__entityModel": "Employee",
"__GlobalStamp": 0,
"__COUNT": 50,
"__SENT": 50,
"__ENTITIES": [ ... ],
"__FIRST": 0
}

Accessing a Removed Entity Set

Request:

GET /rest/Employee/$entityset/3BA2B71499244F60A38CD51E11ACDDF8

Response:

{
"__ERROR": [
{
"message": "The \"3BA2B71499244F60A38CD51E11ACDDF8\" entity set cannot be found",
"componentSignature": "dbmg",
"errCode": 1802
}
]
}

Recreating an Entity Set with $savedfilter

If an entity set is removed and then recreated using $savedfilter, the timeout is reset to 10 minutes:

Request:

GET /rest/Employee?$filter="salary>50000"&$method=entityset&$savedfilter=true

Best Practices

  • Set Appropriate Timeouts: Choose a timeout duration that balances performance and resource utilization.

  • Monitor Cache Usage: Regularly check the cache for expired or unused entity sets to optimize memory usage.

  • Handle Timeouts Gracefully: Implement logic to handle cases where the entity set may have expired or been removed from the cache.