How is the timeout of an API, resource or operation defined and how does it work?

The timeout of a call is the total time available for a request to be processed and answered. When a request is received but the backend doesn’t send a response within the available time, the call is aborted and an error (504) is returned.

How is the timeout defined on Sensedia API Platform?

The timeout of requests is set in more than one place on the Platform and there is a hierarchy:

  1. The gateway works with a default timeout of 60 seconds.

  2. Users may define a specific timeout for an API, resource and/or operation. This can be set by value in seconds or by environment variable. In this case, the more specific timeout overwrites the more generic timeout, but the gateway timeout will always be respected.

    Example of how it works:

    Imagine you create an API with two resources: /resource1 and /resource2. For the API as a whole, you set a timeout of 30 seconds. For /resource1, you set a 10-second timeout for the resource as a whole, but you also set a 40-second timeout for the POST operation and a 20-second timeout for the GET operation. You create another operation for this resource, a PUT operation, but you don’t set any specific timeout for it. You also don’t set any timeout for /resource2.

    Which timeout will be valid for each resource?

    • /resource1 has several operations: the GET will follow the 10-second timeout that was set and the POST will follow its 40-second timeout. The PUT operation has no timeout set, so it will follow the 10-second timeout of the resource.

    • /resource2 has no timeout set. It will therefore follow the timeout of the API, which was 30 seconds. All operations on the resource will follow this timeout, unless a different value is set for each operation.

Setting timeout values

Now that you understand the inheritance of timeouts, it’s worth going over the ways you set the values.

Default gateway timeout

The gateway timeout has a default value of 60 seconds and can’t be changed by users. This value is calculated to be more than enough for HTTP requests and working with higher values can mean a severe performance compromise.

Why does a high timeout compromise performance?

To make the gateways scalable and reliable, we work with performance limits that protect the entire API ecosystem. The timeout is one of the tools that helps protect the system by preventing excessive accumulation of requests to be processed at the same time (which we call threads). If you have an API that hits a slow backend and you increase the timeout to ensure that the backend is able to respond to requests, this generates an increase in threads. When the processing limit of the gateway is reached, incoming requests are barred, even if they are for APIs that have a lower timeout. In other words, good API governance calls for parsimony regarding the timeout of your entire ecosystem.

Timeout of APIs, resources and operations

Setting specific timeout values for an API, resource or operation is done in the flow of an API (APIs  Desired API  Edit Flows).

On the flow edit screen, the timeout value is entered in the API Destination window, which is item 3 in the image below. On items 1 and 2 of the image we define whether the settings of the API Destination we are accessing pertains to all resources of an API or a specific resource (item 1 — Resources field) and all operations of a resource or a specific operation (item 2 — Operations field):

flow timeout

When you open the API Destination window, you can fill in the field Timeout with the value in seconds or with an environment variable.

The value entered will be respected if it is less than or equal to the gateway timeout. If no value is entered, the gateway will consider the next value in the hierarchy explained above.

When to include an environment variable?

You can set the timeout as an environment variable. In this case, you must include the variable name in the field Timeout but the value itself must be set on Environments  chosen environment  Environment Variables. In this case, the value will be unique to the environment that contains the registered variable.

When the timeout is set as an environment variable, you can:

  • Include the variable in several different APIs/resources/operations. If you want to modify the timeout value of all these objects at the same time, simply change the value of the variable in the environment, without having to open each object to make the change.

  • Define distinct timeouts based on the environment to which an API is deployed. For example, you can include the timeout in the API Destination window as a variable named timeout. Then you can include the timeout variable in two different environments — say "Env1" and "Env2" — but in each environment enter a different value (10 seconds for "Env1" and 20 seconds for "Env2"). When the API is deployed to "Env1", its timeout will be 10 seconds, but when it’s deployed to "Env2", it will be 20 seconds.

Check the documentation about environment variables.

The same performance considerations regarding gateway timeout that we raised above apply here. Whenever you register a high timeout value for an API/resource/operation, you should keep in mind that there may be performance compromise and increased risk of API unavailability if your backend can’t respond quickly to incoming requests.
Thanks for your feedback!
EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]