Session management
Session management is one of the most important aspects of developing a client that calls into Integration Server. Failing to re-use sessions properly will result in Perceptive Content Server having to create a brand new session for every call which will severely impact performance on both the server and database. On the other side, over-use of a single session between multiple accounts may limit the throughput of operations due to Integration Server only handling one call at a time per session. Finally, some aspects of Perceptive Content Server are based on session (such as Workflow locks) so failing to use sessions properly may prevent proper use of that functionality.
Initiating a session
A session is created any time an existing, valid session is not provided to an Integration Server request. In order to initiate a new session, user credentials must be provided in some way. They can be passed over via the Authorization
header, the tandem of X-IntegrationServer-Username
/X-IntegrationServer-Password
headers, or through an SSO token (depends on the SSO provider). When a new session is initiated, a session hash will be returned via the X-IntegrationServer-Session-Hash
header. Although a session may be established by making a GET /connection
request, any call in Integration Server will establish a connection if appropriate credentials are provided.
Maintaining a session
To use a previously established session for a request, the session hash for that session should be provided to the X-IntegrationServer-Session-Hash
request header. The X-IntegrationServer-Session-Hash
response header will always contain the session hash that was used to process the call. By default, a session will automatically expire if it has not been used in the past 60 minutes (this is configurable within Perceptive Content Server). Whenever a session is no longer needed, it should be deleted by making a DELETE /connection
request.
Session issues
If a session hash is provided but the session is invalid (never existed or has expired), there are two possible responses based on other headers. If credentials are provided in addition to the session hash, a new session will automatically be generated, the call will be processed as normal, and the new session hash will be returned. If credentials are not provided, a Status Code
of 401, an X-IntegrationServer-Error-Code
of UNAUTHORIZED_ERROR, and an X-IntegrationServer-Error-Message
prompting for credentials will be returned. When maintaining sessions, invalid session hashes should be cleaned up immediately so that they are not repeatedly used (repeatedly using an invalid session hash will repeatedly create new sessions automatically if credentials are provided).
Best practices
- Maintain session hash for any unique session
- Always compare session hash on response to session hash on request for changes
- Close session as soon as it is no longer needed