API configuration

This topic describes the IPS configuration settings for the Planning Space Web API.

The IPS configuration specifically for the OData APIs (i.e., the API endpoints used to retrieve data from Planning Space), also known as Integration Services, is covered in a separate topic, see Integration Services (OData).

For detailed information about the Planning Space Web API, see the Planning Space Web API Guide.

The IPS Server settings mentioned here can be set in the IPS Manager web interface, or using the IPS Admin API (see the IPS Admin API Guide), or using the IPS PowerShell module (Automation cmdlets). To access any of these you will need to have the user credentials for an authorized IPS Administrator.

API response compression

IPS server machines can be configured to apply response compression to API requests. This is controlled by the service setting 'ResponseCompression'. The setting will be the same for all server machines and all tenants. It applies to all tenant web and API endpoints.

Note: By default the service setting 'ResponseCompression' is set to 'HttpOnly', so that all non-secure API requests will have compression applied to response data.

There are potential security vulnerabilities associated with API response compression over secure HTTP (i.e., HTTPS) connections. For this reason, compression is not enabled by default for HTTPS connections to IPS servers. If you have any concerns about the use of response compression, please contact Quorum Support for advice.

The possible settings for 'ResponseCompression' are 'Off' for no compression, 'On' for compression of all HTTP and HTTPS traffic, or 'HttpOnly' (default) for compression to be applied to HTTP traffic.

Web Request Processor Affinity

This is a server-level setting for each machine which applies to all API requests for all of the Planning Space applications, and it determines the 'CPU affinity' of an API request, that is, it decides which CPU cores of a machine will be available to the IPS Server to process the API request. In order to set the affinity you will need to know how many CPU cores are present in the machine.

The affinity is expressed as a hexadecimal number, which is conventionally written with '0x' (zero x) on the front. (For example, 0xF is hexadecimal F (which is also written f), which is decimal 16.)

It's easiest to understand CPU affinity by thinking in binary numbers, for a concrete example. Suppose a machine has 4 cores: these are usually named 'CPU3', 'CPU2', 'CPU1' and 'CPU0'. Each core can be made available to a process (state '1') or not made available (state '0'). Hence you can specify the whole affinity state as a binary number, such as '1000', meaning that CPU3 is available and the other cores are not available. Or, 0011 would mean that CPU1 and CPU0 are available. Notice that the binary number is effectively written 'in reverse' with the highest-numbered core specified first.

All you need to do to write the affinity for the IPS setting is to express the binary number in hexadecimal, so 1000 is 0x8 for example.

The default affinity setting for 'Web Request Processor Affinity' in the case of a 4 core machine is 0xE, in binary that is 1110, which means that 3 cores (CPU3, CPU2, CPU1) are made available to process API requests. The rule used for the default is that 75% of the total number of cores in the machine will be made available (which works apart from the case of a 1 core machine - which has only one possible affinity worth talking about, or a 2 core machine where the default is 0x2 or 10).

For an 8 core machine, the default setting is 6 out of 8 cores, arranged 11111100, that is affinity 0xFC (or 0xfc, which is the same number).

You can adjust the 'Web Request Processor Affinity' setting to vary the share of total IPS Server processing capacity that is made available for API requests. If API requests are running too slowly (e.g., you have some API client-based services that are stalling or running too slowly) you could make more CPU cores available, and (if necessary) modify some of the other IPS affinity settings (see Servers configuration) to allow other types of processes (such as batch jobs) to have less access to IPS processing capacity. Or vice versa, where priority access to processing capacity needs to be granted to the other types of processes.

When the affinity setting is changed, the IPS process on the machine must be re-started for the new setting to take effect.

You can use the IPS PowerShell module to get the processor affinity value using the following commands. First, create a connection to IPS:

Connect-IPSManager https://ips.mycompany.com

Query the current setting:

Get-ServerSetting -Category 'Web Server' -Name 'Web Request Processor Affinity' -Server ips1.mycompany.com

The output will be the hexadecimal value of the setting, '0xE' by default.

You can change the affinity with the command:

Set-ServerSetting -Category 'Web Server' -Name 'Web Request Processor Affinity' -Server ips1.mycompany.com -Value 0xF