Request header

Application management : Tools : REST API : Advanced features : Request header

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 parameters that are 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
ArchiveMode	Retrieves either all records or only the unarchived records. • unarchived • all	String
SerializeNulls	Returns all requested fields or only the fields that hold a value.	Boolean (true/false)
NeutralDateTimeAsString	Returns a neutral DateTime as a string in the format: YYYY-MM-DD hh:mm:ss	Boolean (true/false)

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 it 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 2024 would then be 2024-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

ArchiveMode

• If the header does not contain the ArchiveMode parameter, the default value unarchived is active and only unarchived records are returned.

• If the header contains the ArchiveMode parameter and it has a value, this value needs to be validated.

◦ If the value is unarchived, the response only contains unarchived records.

◦ If the value is all, the response contains both archived and unarchived records.

Examples

Code header	Result
all	All records will be returned.
unarchived	Only unarchived records will be returned.
anything other than all or unarchived	unarchived will be applied, only unarchived records will be returned.
<empty>	unarchived will be applied, only unarchived records will be returned.

SerializeNulls

• If the header does not contain the SerializeNulls parameter, the default value false is active and only fields with a value are returned.

• If the header contains the SerializeNulls parameter and it has a value, this value needs to be validated.

◦ If the value is false, the response only contain fields that hold a value.

◦ If the value is true, the response contains all fields that are requested, no matter whether they hold a value.

A field is considered empty if it either contains a NULL value or an empty string.

Examples

Code header	Result
true	All field will be returned
false	Only fields with a value will be returned
If anything other then true or false	false will be applied, only fields with a value will be returned
<empty>	false will be applied, only fields with a value will be returned

NeutralDateTimeAsString

• If the header does not contain the NeutralDateTimeAsString parameter, the default value false is active and neutralDateTime-fields are returned as an object with a Date- and a Time-property.

• If the header contains the NeutralDateTimeAsString parameter and that has a value, this value needs to be validated.

◦ If the value is false, the response contains neutralDateTime-fields as an object with a Date- and a Time-property.

◦ If the value is true, the response contains neutralDateTime-fields as a string in the format YYYY-MM-DD hh:mm:ss.

Examples

Code header	Result
true	All neutral DateTime-fields are returned as a string with format YYYY-MM-DD hh:mm:ss.
false	All neutral DateTime-fields are returned as an object with a Date- and a Time-property.
anything other than true or false	false will be applied, neutral DateTime-fields are returned as an object with a Date- and a Time-property.
<empty>	false will be applied, neutral DateTime-fields are returned as an object with a Date- and a Time-property.