Managing Common REST API session tokens and user tokens

The Common REST API (CRA) uses user tokens and session tokens to manage your API usage:

When you log in, you receive a user token that identifies you as a valid user of the API.
Each time you access a reusable service, you receive a session token. A session token is a character string that identifies the session you are accessing to allow you to continue to access the same data.

Both types of tokens expire:

User tokens expire if you don't use them within the time set by the timeout value.
Session tokens expire immediately unless you specify otherwise as described below.

For more information, see Reusing a session token.

Depending on your system resources, the number of sessions that you can have open simultaneously might be limited. BMC recommends that you reuse the associated session token for multiple getData or data requests from the same view.

Tip

Because all data for the view is cached on a data or getData request, reusing the session can result in better performance and optimum resource usage.

Both user and session tokens expire if you don't use them. If you do not plan to reuse a session token it's not necessary to use the close parameter. Unless you indicate that you want the session to stay open, it closes immediately.

Best practice
When you are done with a session, it is best to issue a close parameter directly to prevent too many sessions from being open simultaneously. For more information, see Closing a session.

You can also modify the timeout value which controls the amount of time tokens stay valid. If you do not expect to reuse any sessions, reduce the timeout value so that sessions time out faster when not closed directly.

If you intend to reuse sessions, you can set the timeout value to a higher value so that you have longer to reuse the session. In this case, it is important to close unneeded sessions directly when you don't need them anymore, because it will take them longer to timeout and consume resources.

Opening a session

To start a session and keep it open, use the following syntax:

https://<hostName>:<portNumber>/cra/ServiceGateway/Services/<serviceName>/products/<productName>/views/<viewName>/data?close=false

Example

If the response looks like this:

Result example:
{
   "rc": 0,
   "viewName": "JCPU",
   "startRow": 1,
   "numRows": 20,
   "session": "a65b38ec-3ed0-4102-824a-d5e6d70f6bc9",
....

Include session="a65b38ec-3ed0-4102-824a-d5e6d70f6bc9" in subsequent requests as the sessionId.

Reusing a session token

To reuse a data session, use the following header parameters:

Append the following parameter to the initial data or getData request:

close=false

On subsequent data or getData requests on the same session, use the following header parameter:

session=<sessionId>

Example

https://<hostName>:<portNumber>/cra/ServiceGateway/Services/<serviceName>/products/<productName>/views/<viewName>/data?close=false

On the final getData or data request, use the following header parameter:

session=<sessionId>

and add the following parameter to the request:

close=true

Closing a session

Leaving sessions open, uses resources. If you no longer need a session that is open, you can use the following syntax to close it:

https://<hostname>:<portnumber>/cra/ServiceGateway/Services/<servicename>?close=true

Using the keepAlive command

If you want to keep a session alive for future reuse, issue a keepAlive command. You can issue keepAlive for either a user token or a specific session. The session parameter is optional. In either case, the user token is kept alive while any associated sessions are alive.

Examples

https://<hostname>:<portnumber>/cra/ServiceGateway/Services/<servicename>/keepalive

https://<hostname>:<portnumber>/cra/ServiceGateway/Services/<servicename>/keepalive?session=<sessionId>

In the Body, set the following key:
userToken=<userToken>
<userToken> is the token issued when you logged on. For more information, see Logging-in-to-a-service-using-the-Common-REST-API.