How to create a REST API session
An authenticated REST session must be created before API requests can be sent or received. Use a REST client to create a REST API session to interface with the software.
Prerequisite(s):
♦A REST client of some type is required.
Creating a REST API sesssion is similar to logging in to using a web browser. The only difference is that a web browser (in the typical sense) is never used. Instead, you need an application capable of sending and receiving HTTP requests—a REST client. REST clients are different than web browsers, although some REST clients are built on-top of web browsers like
Chromium because they share interchangeable parts. Your institution, or contractor if you hired one, might be using a proprietary or unique REST client, but the underlying workings are the same for each. As we documented our REST API, we experimented with a few different REST clients, including
cURL. Ultimately, the
Postman REST client was our favorite, and it was used to create our code samples and examples in these documents.
To create a REST API session:
1. Create a POST request.
a. Point the POST request to base-uri/session. b. Set the Accept header to application/json or application/xml.
c. Set the Content-Type header to application/json.
Note: The only content type accepted for creating a REST API session is
JSON.
d. Populate the request body with a JSON object named session containing username and password and passing a valid user name and password.
Figure 1: Select All
{
"session" : {
"username" : "julia",
"password" : "birdwatcher25"
}
}
Tip! Your user name and password are
never sent in clear text. Every request and response uses
TLS.
For Observer Analyzer trace extractions, The username must be admin if Observer is not managed by OMS; otherwise it is your OMS user name.
The password OMS password if using an OMS user; otherwise, it is the Observer GigaStor probe administration password that was set in Observer. If a password was not set, then use an empty string (””).
When logging in to an Apex system (full license) managed by OMS:
▪You are being asked for OMS user credentials.
▪Use your OMS user name and password.
▪Depending on your OMS authentication settings, this could be your Active Directory, LDAP, RADIUS, or TACACS+ logon credentials—or the OMS local user list.
When logging in to an Apex system (full license) not managed by OMS:
▪You are being asked for Apex user credentials.
▪Use a user name and password that was set up in Apex.
▪You may also try admin/admin if the admin password was never changed.
2. Send the POST request to base-uri/session. replies with a 200 OK code if successful. If you receive the 200 OK, you successfully created a REST API session. Now the session must be invoked each subsequent request you make. This is done using the
Cookie header that you will create.
3. Create another header named Cookie to place alongside Content-Type and Accept.
4. Examine the response body for a string or cookie containing SessionApexId that leads to a long string of characters.
Example: The full string might look like this: 14967b34a4c611523116fd. This is your session ID.
5. Set the Cookie header to SessionApexId=14967b34a4c611523116fd, replacing the example string of characters with the one you extracted from your POST response.
You successfully created a REST API session. You sent a
POST request with a user name and password, and the REST API responded with a 200 OK and a session ID. The session ID must be used for all subsequent requests. The session will last until timing-out from inactivity or it is ended with a
DELETE request on
base-uri/session.
Upon successful creation of a REST API session, the full response body might look similar to this:
Figure 2: Select All
Sessions automatically time out after inactivity
For security reasons, sessions automatically close based on a period of activity.
Product | Details |
|---|
Apex | A session timeout is optional. If set, sessions automatically close after a user configurable amount of time. See Apex General Settings. |
GigaStor | All sessions automatically close after 10 minutes of inactivity. This value is not configurable. |
OMS | |