Skip to content

Getting Started

Enable REST API

Polarion's REST API is disabled by default, but administrators can enable it by setting the following property in the polarion.properties file: com.siemens.polarion.rest.enabled=true

(Polarion X users can contact their local partner or SaaS operations representative.)

Enable the Swagger UI

The Swagger UI is generated automatically from Polarion's OpenAPI implementation. When enabled, your development team or end consumers can view and interact with API resources without needing any implementation logic in place.

Swagger UI

To enable Swagger UI, set the following property to true in the polarion.properties file:

com.siemens.polarion.rest.swaggerUi.enabled=true

Note

  • Both properties are system-level properties so you must set them in the polarion.properties file before starting Polarion.
  • They are both disabled by default to give you more control over security.
  • com.siemens.polarion.rest.enabled must be set to true for com.siemens.polarion.rest.swaggerUi.enabled to have an effect.

Access REST API

If you enabled the REST API you can access it with the following root URL.

https://[Your_Polarion_server]/polarion/rest/v1

If you also enabled the Swagger UI you can view it in a web browser at the following URL.

https://[Your_Polarion_server]/polarion/rest/v1

Polarion's Swagger UI

URI Structure

Polarion's REST API lets you access resources (data entities) via URI paths. To the REST API, your application makes an HTTP request and parses the response. The URI structure for Polarion REST API resources is as follows:

https://[Your_Polarion_server]/polarion/rest/[api-version]/[endpoint_URL_part]?[URL_parameters]

Example

  • https://myhost/polarion/rest/v1/projects/myProject/workitems/WI-123?revision=5
  • The URI is influenced by whatever is in the base.url property of the polarion.properties file on your Polarion server.

REST API Versioning

It's easy to determine the REST API version number because it is right in the URI: (v1 in the example below.)

Example

https://myhost/polarion/rest/v1/projects

The REST API is backward compatible, so any implementation you deploy from a previous version will work whether or not you choose to update to a newer version.

New versions will only be released when significant changes (like the addition of renaming and removing are added). There may be additional patch updates or minor changes, but they will not affect existing implementations.

REST API in a Cluster setup

A Clustered setup is a group of Polarion servers (application nodes) that access a single instance of shared data. (See the Deployment and Maintenance Guide for more information.)

When using REST API in a Clustered setup:

  • Use the Load Balancer URL (the default base URL) to access the REST API.

    (Requests should not be sent directly to individual nodes.)

  • If you want to access the Swagger UI (if enabled), you should also use the base.url.

  • REST API response links always point to the Load Balancer URL (base URL), regardless of the node that processes the request.

Notes

  • Polarion properties related to the REST API should be configured on the Shared Services server machine.

    (In the polarion.properties file shared with nodes.)

  • There is no need to safelist the nodes in a Cluster environment with the com.siemens.polarion.rest.cors.allowedOrigins property. (They are allowed by design.)

  • Updating the same resource in rapid succession may result in a conflict error because the calls end on other nodes are not propagating fast enough.

    (Propagation changes only occur every three seconds by default.)

Authentication

The calls of the Polarion REST API are authenticated via JSON Web Tokens. Every call is individually authenticated, there are no persistent sessions.

Currently, the only supported method to authenticate and access the Polarion REST API is using Polarion personal Access Tokens. The personal Access Token is an existing feature. For example, it is already used for SOAP Web Services.

Any Polarion user can create and manage their tokens. Polarion administrators can immediately revoke individual tokens in an emergency.

For more information on how to generate or revoke a personal Access Token in the Polarion UI, see Access Token support.

Authorization Header

Provide a Polarion personal Access Token in the Authorization header of each request if you try to access Polarion REST API with any technology:

Authorization: Bearer {personal_access_token}

Example

Authorization: Bearer 32ewrgdtfhdtdr54ztrhdfjfg

If the token is missing or is invalid, the 401 Unauthorized response is returned.

The API reference documentation in SDK has further examples on how to provide the authentication token using the command line or different scripting languages.

To test the Polarion REST endpoints using the Swagger UI, click Authorize and authorize yourself using your Polarion personal Access Token.

REST API access from Polarion without PAT

To access the Polarion REST API, you can issue an HTTP request using JavaScript while within an active Polarion session without having to generate a Personal Access Token (PAT). This means you can fetch data from the API without needing a PAT.

To authenticate through the Polarion REST API, you can use the X-Polarion-REST-Token header, which is bound to the authenticated session and follows the same lifecycle. (This means you don't need to supply a PAT when making API calls.)

The generated X-Polarion-REST-Token is only valid for the current session and becomes invalid once the user logs out.

Tip

This feature is useful in Report Page widgets, where you can fetch data on demand.

To use the X-Polarion-REST-Token, add the following property to the polarion.properties file:

com.siemens.polarion.rest.security.restApiToken.enabled=true

Warning

Polarion REST API using the X-Polarion-REST-Token can perform read/write operations on behalf of the user viewing a Polarion Report Page. Therefore, ensure that write Page permissions are defined correctly and are only enabled for trusted users to prevent malicious scripts from running on users without their knowledge.

To authenticate your Polarion REST API call, supply the X-Polarion-REST-Token header in each Polarion REST API request.

The value of the header is obtained from the top.getRestApiToken() function, which generates the session-bound token.

Here's an example of how to authenticate using the X-Polarion-REST-Token token:

<script>

// declaration
function fetchRestAPI(resource, options) {   
    var restToken = top.getRestApiToken()
    if (options == undefined) {
        options = {};
    }
    if (options.headers == undefined) {
        options.headers = new Headers();
    }
    if (options.headers instanceof Headers) {
        options.headers.set("X-Polarion-REST-Token", restToken); 
        options.headers.set("Accept", "application/json");  
    } else {
        options.headers["X-Polarion-REST-Token"] = restToken; 
        options.headers["Accept"] = "application/json";
    }
    return fetch(resource, options);
}

// invocation
fetchRestAPI("/polarion/rest/v1/projects/drivepilot/workitems/DP-584")
      .then(response => {
         console.log("fetchRestAPI response: ", response);
          if (!response.ok) {
              throw new Error(`HTTP error! Status: ${response.status}`);
          }
         return response.json();
      })
      .then(json => {
         console.log("fetchRestAPI json: ", json);
      });

</script> 

Authorization

Most operations in this API require permissions. Polarion permissions are fully applied, so the calling user must have the necessary permissions for an operation to use it.

If the available permissions are insufficient, the 403 response is returned.

Example

The user does not have the required permissions to read project A:

  • Example Request:

    GET /polarion/rest/v1/projects/A

  • Response Body:

        {
            "errors": [
             {
                 "status": "403",
                 "title": "Forbidden",
                 "detail": "You do not have permission to view Project 'A'."
             }
            ]
        }
    

Community

Connect and Collaborate with Industrial Professionals and Join the Community!

Click to load comments