Request header
Planon uses sessions to store general information that determines the behavior of the application.
This can be information about the language, data section (property set) or reference date. Especially the last option is very important in the area of Spaces & Workspaces.
In order to use this information in REST API, you must add a parameter to the HTTP header. The header itself carries meta information and the parameters carry actual data.
Headers are grouped together alphabetically. If no parameter is set, the response will fall back to the default.
The following table lists the parameter that is currently available to set session data.
Parameter | Contains | Type |
|---|
ReferenceDate | Sets a sessions reference date. Note that you should enable the use of reference date to have any effect. | Date |
How it works
If a request is received, a check for custom parameters is performed. All values from custom parameters must be stored.
First, the session is initialized with default settings. The values for these settings are stored in the user profile. Once the session is initialized the stored values from the header parameters must be assigned to the appropriate session properties and only then the request itself can be processed.
ReferenceDate
You can use a reference date to access time-dependent data. Setting a reference date allows you to retrieve only business objects that are valid either on, before or after this date.
• If the header does not contain the ReferenceDate parameter, the default date (current date) is active and nothing is done.
• If the header contains the ReferenceDate parameter and that has a value, this value needs to be validated:
◦ If the value equals none, the useReferenceDate session parameter is set to False. This means that the reference date is not taken into account when filtering business objects.
◦ If the value does not equal none, the value must be validated for a proper date. This date must comply to the ISO8601-standard, which is YYYY-MM-DD. In this example, the 1st of October 2023 would then be 2023-10-01.
◦ If the date does not match this format or the date itself is invalid, the current date stays active.
• If the date passes validation, the ReferenceDate session parameter is set to the given date.
Example
ReferenceDate: 2023-10-01
Content-Type: application/json
Authorization: PLANONKEY accesskey=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.[...]r_3LCaao7RxYuho6Q
User-Agent: PostmanRuntime/7.33.0
Accept: */*
Postman-Token: e6be7525-4749-48e2-9228-1f7d2abcaabe
Host: tbschout-acc.plnd.cloud
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 68
Cookie: JSESSIONID=FC792A8BF242D76A547339933F0FD6B1; PLANONINGRESS=f262276955e44[...]292805c80