Skip to content

Time Zone Aware APIs

This documentation outlines the default behavior of IFS APIs and introduces a new feature aimed at enabling time zone awareness.

Default Behavior

When clients submit values in the request body or parameters of type Timestamp formatted as yyyy-MM-dd'T'HH:mm:ssZ in UTC timezone, IFS APIs interpret these values based on their design and logic, so it might be in the server's time zone, user's time zone or something like a site time zone. Despite the apparent UTC format in the request, the API processes the timestamp as a datetime in the time zone associated with the design of the endpoint, deviating from a strict adherence to UTC.

API Specification

Not all APIs are Time Zone aware. Time zone-aware APIs can be identified through the API documentation. This information is highlighted under each API endpoint in the dedicated section labeled 'Timezone Information'.

At present, there exists a single variation of time zone-aware APIs, namely the 'server' variation. A 'site' variation is planned for introduction in future releases.

Opt-in Behaviour

To address the need of time zone aware APIs, a new header, X-Ifs-Time-Zone-Aware-Request, has been introduced. When set to true, this header triggers a modification in the API's behavior, specifically regarding timestamp type values within the request body and parameters. Timestamps formatted as yyyy-MM-dd'T'HH:mm:ssZ in UTC timezone are then treated as date times in UTC.

Please be aware that the time zone-aware behavior is activated only when the X-Ifs-Time-Zone-Aware-Request request header is set to true. If this header is not set or set to false, the default behavior will be applied.

When the X-Ifs-Time-Zone-Aware-Request header is set to true and the API used is not a time zone aware API, if there are timestamps associated with the request in the request body or request parameters, the request will fail.

If you are accessing CRM related end points, refer this for more information.

Endpoints associated with Server

For Endpoints associated with the server's timezone, the server takes responsibility for converting timestamp values associated with incoming requests to its local time zone before proceeding with further processing.

In order to better understand this, refer to the below diagram illustrating the server's behavior when receiving timestamp values from clients.

In this diagram, the presence of the X-Ifs-Time-Zone-Aware-Request header dictates the server's behaviour. If the header is set to true, the server converts the timestamp value to its local time zone. Conversely, if the header is not present or set to false, the server assumes the timestamp is already in its local time zone, and no conversion occurs. It's important to note that this works as above only because the API used here is a time zone aware API.