Before calling REST API

This section explains what you should consider before calling any REST APIs.

Authenticate

To call any ALM Site Administration REST API request, you should first get authenticated to obtain the LWSSO token as a cookie in the request header.

We recommend you use the alm-authenticate or login methods to get authenticated.

For details about authentication, see Authenticate.

Open a site session

After authentication, POST /qcbin/rest/site-session to open a site session by using the LWSSO token you obtained from authentication.

This request returns ALM_USER, QCSession, and XSRF-TOKEN in Set-Cookie.

The QCSession token is required in all subsequent project-level APIs. The XSRF-TOKEN token is required in all subsequent non-GET APIs.

For details, see Session Management.

Headers

API headers are like an extra source of information for each API call you make. Their job is to represent the meta-data associated with an API request and response. Here are some of the most common API headers you encounter when using ALM REST API.

Cookie

Cookies are used to store small amounts of data. Except for the authenticate and session interfaces, you should set Cookie in all other interfaces to what you received from Set-Cookie. Pass Cookie for every other request in the request header. For example:

Copy code
Cookie: LWSSO_COOKIE_KEY={}; ALM_USER={}; QCSession={}; XSRF-TOKEN={};

Accept and Content-Type

The Accept header is added to tell the server what types of response content your application accepts. You can refer to the Media type value of the response in the resource.

The Content-Type header is added to tell the server what the media type is in the message body so that the server can parse the request body. It is usually required in PUT and POST requests. The value provided is usually application/json or application/xml. You can refer to the request body in every resource for details.

X-XSRF-TOKEN

ALM checks whether the X-XSRF-TOKEN header is included in all requests, except the ones that use the GET HTTP method. If the header is missing, the REST API calls fail. After getting authenticated, the ALM server returns the value of XSRF-TOKEN cookie. In all your subsequent requests, except for the ones that use the HTTP GET method, you should include the X-XSRF-TOKEN header (that is the value of XSRF-TOKEN cookie) in the requests.

For details, see Send X-XSRF-TOKEN header with all requests.