Basic Concepts¶

Requests and responses¶

Requests¶

Client requests can contain a body unless they are GET requests. The format of the body should be as follows:

• application/json

• multipart/form-data (For requests that manage attachments. See the Attachments section for details.)

Responses¶

Server responses may contain a body unless they are a PATCH request.

The body's format should be as follows:

• application/json

• application/octet-stream

  (For requests that manage attachment content. See the Attachments section for details.)

If there's a communication issue (for example, the Polarion server is down), the client receives a response with a body in text/html format.

Request headers¶

You must set up client request headers correctly.

The Accept header below indicates the expected format for server responses.

If set incorrectly, Polarion returns the following error:

{    
    "errors": [        
         {            
            "status": "406",             
            "title": "Not Acceptable"
        } 
    ]
} 

The Accept header is optional and can be omitted.

You can also set them to a wildcard value (*/*) or a concrete format based on the request:

-H "accept: */*"

-H "accept: application/json"

The Content-Type header indicates the body format of the request being sent. If set incorrectly, the following error response is returned:

{     
    "errors": [         
        {             
            "status": "415",             
            "title": "Unsupported Media Type"         
        }     
    ] 
}

The Content-Type header is more strict and cannot be omitted or set to a wildcard */*.

The Content-Type header must match the format of the request body:

-H "Content-type: application/json"

Typical responses¶

The following are typical responses you receive while making requests to Polarion's REST API.

• 200 OK: For GET requests.

• 201 CREATED: For POST requests creating a new object/resource. The resource identification is returned.

• 204 NO CONTENT: For successful POST or PATCH requests that did not result in creating new resources. The updated content is not returned to save bandwidth.

• 400 BAD REQUEST: With a detailed message if the request is malformed or otherwise invalid.

• 401 UNAUTHORIZED: When the user it not authenticated.

• 403 FORBIDDEN: When the authenticated user does not have sufficient permissions for the request.

• 404 NOT FOUND: When the request contains a non-existing parameter and/or Request Body.

• 406 NOT ACCEPTABLE: When the requested Accept header does not match the server's criteria.

• 409 CONFLICT_CODE: When the POST Request Body contains an existing ID.

• 415 UNSUPPORTED MEDIA TYPE: When the request contains an unsupported media format.

Resource types and identification¶

Every resource provided by the Polarion REST API is uniquely identified by a pair of strings: type and id.

Where a particular revision of a resource needs to be referenced, these two strings are accompanied by a third one, the revision. (Not all resources support revisions.)

Use the Resource IDs as opaque values: they are not expected to be parsed, sliced, or combined by clients. Use them for example as keys in maps, or to match references in relationship with the included resources and so on. In most cases, instead of creating an endpoint URL (for example to fetch resource data) the clients should use links returned by the REST API endpoints (see Links).

Resource identification in the primary Data, ID and Type attributes¶

GET /polarion/rest/v1/projects/myProject/workitems/WI-123

{
  "links": {...},
  "data": {
    "type": "workitems",
    "id": "myProject/WI-123",
    "attributes": {
      "id": "WI-123",
      "type": "requirement"
    },
    "relationships": {...}
    },
    "links": {...}
  }
}

Resource identification in the relationship value (frozen Work Item link)¶

GET /polarion/rest/v1/projects/myProject/workitems/WI-1/linkedworkitems/relates_to/myProject/WI-2?fields[linkedworkitems]=@all

{
  "links": {...},
  "data": {
    "type": "linkedworkitems",
    "id": "myProject/WI-1/relates_to/myProject/WI-2",
    "attributes": {
      "role": "relates_to",
      "revision": "1234"
    },
    "relationships": {
      "workItem": {
        "data": {
          "type": "workitems",
          "id": "myProject/WI-2",
          "revision": "1234"
        }
      }
    },
    "links": {...}
  }
}

Links¶

Where specified (in the endpoint schemas), Rest API responses can include a link member with one or more named links (URLs).

They can be helpful for clients to make further calls to the REST API that manipulate the data or to get additional information about the returned data.

The following table contains individual link type details:

self

Link to the REST API endpoint request that produced the response (present in the root links section) or to the resource endpoint.

(Present in the resource links.)

related

Link to the REST API endpoint that returns the content of a relationship, present in the relationship links in the primary resource.

(If the relationship has its own endpoint).

content

Link to the REST API endpoint that downloads the file content of an attachment, present in the resource links of attachment resources.

portal

Link to the Polarion portal, present in the resource links and the list of response links.

(Currently, it is only supported by the workitems resource.)

first

Pagination link to the first page, present in the resource links and in the list response links. For more information, see Pagination and resource sets.

prev

Pagination link to the previous page, present in the resource links and in the list response links. For more information, see Pagination and resource sets.

next

Pagination link to the next page, present in the resource links and in the list response links. For more information, see Pagination and resource sets.

last

Pagination link to the last page, present in the resource links and in the list response links. For more information, see Pagination and resource sets.

Link Example¶

• Example Request:

  GET /polarion/rest/v1/projects/myProject/workitems/WI-123?fields%5Bworkitems%5D=title

• Response Body:

{
    "links": {
        "self": "https://myhost/polarion/rest/v1/projects/myProject/workitems/WI-123?fields%5Bworkitems%5D=title"
    },
    "data": {
        "type": "workitems",
        "id": "myProject/WI-123",
        "attributes": {
            "title": "My Title"
        },
        "links": {
            "self": "https://myhost/polarion/rest/v1/projects/myProject/workitems/WI-123",
            "portal": "https://myhost/polarion/redirect/project/myProject/workitem?id=WI-123"
        }
    }
}

Fields¶

The Attributes and Relationships REST API resources are commonly referred to as Fields. In REST API requests and responses they usually correspond with built-in and custom object fields in Polarion. Simple types and enumerations (for example, string, date, and status) are represented as Attributes, while references to other objects, including custom object enumeration fields (for example author, categories) are represented as Relationships. Custom fields are identified by their IDs without any particular prefix or distinction from the built-in fields, the same as in the Polarion UI.

A field is only returned in a REST API response if it has a non-empty value on the particular resource. Therefore, strings fields with an empty value, boolean fields with a false value, and null object references in relationships do not appear in responses, even if they have been specifically requested. However, an empty relationship may be returned if it provides the endpoint link to access the relationship value (for example for adding comments or attachments).

Sparse fieldsets¶

With most GET requests, it is possible to request a particular set of fields to be returned using the fields[resourcetype] URL parameter.

The value of each fields[resource_type] can be one of the following:

• The URL parameter, a comma-separated list of field IDs (attributes or relationships).

• The @basic keyword to include the basic set of fields predefined for the respective resource type.

• A combination of the @basic keyword and additional comma-separated field IDs.

• The @all keyword to include all the available fields for each resource of the given type.

• The empty value, so that no resource fields are returned, only the resource identification and links.

The default set of fields, returned when the fields[] parameter for the given type is not present, may differ based on the context of the request. Requests returning a set of resources will typically return no fields by default, while individual resource result will use the @basic fieldset.

Notes¶

When using Includes, the fields[] parameters apply to all resources of the given type in the response. It is also possible to specify multiple fields[] parameters, for example: GET /projects/myProject/workitems?include=author&fields[workitems]=@basic&fields[users]=name

Sparse fields fields[workitems] apply to all types of work items (see the note in Resource types and identification on the differences between type as a resource vs. type as a field).

If unknown fields are listed in the parameter value, then they are silently ignored. Therefore, it is possible, for example, to request to fetch custom fields that are not defined for all Work Items in a result set without the risk of making a bad request.

When using Swagger UI, there is an autogenerated example to show all the available parameters for fields[], but most of these would not apply, unless you really include the resources of all those types. You would typically use fields[resource_type] for the types to be returned only by your particular request. Also, the Swagger UI uses a different format for the fields parameter input: it is encoded as JSON, but it eventually adds the same individual fields[type] parameters in the generated request URL.

Relationships¶

Each resource can have a relationship to other resources. They are presented alongside attributes.

Resources contain fields that are either Attributes or Relationships.

Relationships let you represent the entire hierarchical structure of a primary resource.

Get Work Item with assignees and comments¶

• Example Request:

  GET https://myhost/polarion/rest/v1/projects/myProject/workitems/WI-100?fields[workitems]=assignee,comments

• Response Body:

{
    "links": {...},
    "data": {
        "type": "workitems",
        "id": "myProject/WI-100",
        "relationships": {
            "assignee": {
                "data": [
                  {
                    "type": "users",
                    "id": "sDeveloper"
                }
              ]
            },
            "comments": {
                "data": [
                  {
                    "type": "workitem_comments",
                    "id": "myProject/WI-100/1
                  }         
                ],         
                  "links": {           
                    "related": "https: //myhost/polarion/rest/v1/projects/myProject/workitems/WI-100/comments"          
                }        
              }      
             },     
             "links": { ... }   
          } 
    }

You can update regular relationships like Assignee or Categories with a PATCH request to the primary resource or through a relationship endpoint.

(See Update using PATCH for details.)

Update a Work Item relationship through primary resource: Add "mTest" user as an Assignee¶

• Example Request:

  PATCH https://myhost/polarion/rest/v1/projects/myProject/workitems/WI-100

• Request Body:

{
    "data": {
        "type": "workitems",
        "id": "myProject/WI-100",
        "attributes": {...},
        "relationships": {
            "assignee": {
                "data": [
                  {
                    "type": "users",
                    "id": "sDeveloper"
                }, 
                {
                    "type": "users",
                    "id": "mTest"
                }
              ]
           }
        }
    }

Update a Work Item relationship through a relationship endpoint: Add "mTest" user as an Assignee¶

• Example Request:

  POST https://myhost/polarion/rest/v1/projects/myProject/workitems/WI-100/comments

• Request Body:

{
   "data": [
         {
             "id":"mTest",
             "type":"users"
         }
     ]
 }

Relationships to dependent resources like Comments and linked Work Items can be manipulated via a dedicated endpoint like https://myhost/polarion/rest/v1/projects/myProject/workitems/WI-100/comments in the example above. (See additional examples in the Linked Work Items section). You can quickly identify these relationships because they include a related link that must be used to add/remove/modify the ties in the relationship section of the GET response of the primary resource.

Update a Work Item relationship: Add a new comment to the Work Item¶

• Example Request:

  POST https://myhost/polarion/rest/v1/projects/myProject/workitems/WI-100/comments

• Request Body:

{
    "data": [
    {
      "type": "workitem_comments",
      "attributes": {
          "resolved": false,
          "title": "Test title",
          "text": {
              "type": "text/html",
              "value": "This is a comment"
            }
        }
    }
  ]
}

• Response Body:

{
    "data": [
      {
        "type": "workitem_comments",
        "id": "myProject/WI-100/2", 
        "links": {
           "self": "https://myhost/polarion/rest/v1/projects/myProject/workitems/WI-100/comments/2"     
        }   
     }
   ]
}

Things to keep in mind¶

Project-level objects, like Categories or Plans, are always referred to by their fully qualified ID when used in REST API requests or results. (This differs from how they appear in Lucene queries, for example.)

• Example Request:

  GET /projects/myProject/workitems?query=categories.id:interface&fields[worktiems]=categories

• Response Body:

{
  "links": {...},
  "data": [
    {
     "type": "workitems",
     "id": "myProject/WI-123",
        "relationships": {
            "categories": {
                "data": [
                  {
                    "type": "categories",
                    "id": "myProject/interface"
                }
               ]
            }
        },
        "links": {...}
    }
  ]
}

Sending an unqualified ID (for example, interface instead of myProject/interface) as part of a PATCH or POST request will typically result in a 400 Bad Request response about an invalid or unresolvable object reference.

Includes¶

When fetching resource data from endpoints, you can request to return additional related resources in the response along with the primary data. For example, if requesting a Work Item's resource, you may also want to know the name of the project it belongs to. Project is another resource in the Project relationship. (You can even return resources that are related to the related resources.)

To define which related resources to return along with the primary data, you must send an include query parameter. The value is a comma-separated list of relationship paths. A relationship path is a dot-separated list of relationship names. The related resources specified by the include parameter get returned in the response as an array in the included member.

By default, no fields of the resources in the included array get returned. To have some fields returned, they must be requested using the fields query parameter for the appropriate resource type. (For example, fields[project]=name. See Fields and Sparse field sets for details.)

Get a project name for a Work Item¶

• Example Request:

  GET /projects/myProject/workitems/WI-123?fields[projects]=name&include=project

• Response Body:

{
    "links": {...},
    "data": {
        "type": "workitems",
        "id": "myProject/WI-123",
        ...
    },
    "included": [
      {
        "type": "projects",
        "id": "myProject",
        "attributes": {
            "name": "My Project"
        },
        "links": {...}
      }   
   ] 
}

Get an Author name and a Project Lead name for a Work Item¶

• Example Request:

  GET /projects/myProject/workitems/WI-123?fields[users]=name&include=project.lead,author

• Response Body:

{
    "links": {...},
    "data": {
        "type": "workitems",
        "id": "myProject/WI-123",
        ...
    },
    "included": [
      {
        "type": "users",
        "id": "myProjectLead",
        "attributes": {
            "name": "My Project Lead"
        },
        "links": {...}
    },
    {
        "type": "users",
        "id": "myAuthor",
        "attributes": {
            "name": "My Author"
        },
        "links": {...}
    }
  ]
}

Notes¶

• The relationships used in the include parameter do not affect which fields are requested. (For that, you must use the fields query parameter.) So in the second example above, the author relationship of the Work Item is not returned. (Only the author is returned in the included member.)

• When a relationship path is used in the include parameter, only the leaf resources are returned in the included member. So in the second example above, the project resource is not returned in the included member, only its lead user is returned. If the project also needs to be returned, adjust the query parameter to, for example, include=project,project.lead.

• If some relationship in a relationship path in the include parameter is not found, the path is ignored, so it does not cause an error response. This is because relationships may be derived from custom fields so is only present in some of the primary resources.

• When the user does not have permission to read some of the relationships in a relationship path, this path will be skipped, and a related error will be returned in the meta.errors member in the response.

• If more related resources are specified than a limit of 100, only this limited number of resources is included in the response. The limit is configurable via the com.siemens.polarion.rest.maxPageSize property.

Limited responses and pagination¶

To prevent a large number of resources being returned at once, the REST API implementation applies certain default limits. The following sections describe how these limits are applied to various responses.

Pagination of resource sets¶

You can retrieve resource result sets in manageable chunks using pagination. Pagination is available for those REST API endpoints that return potentially large sets of resources, like Work Items, projects, comments, and so on.

Currently, the default page size is set to 100 and you can configure it using the com.siemens.polarion.rest.defaultPageSize system property. You can also set a non-default page size by using the page[size] URL parameter. You can configure the upper limit of the client-requested page size using the com.siemens.polarion.rest.maxPageSize system property.

By default, the first page of the results is returned, and you can request other pages either by directly using the page[number] URL parameter, or by following the pagination links that come as part of each response. For example:

"links": {

    "self": "https://myhost/polarion/rest/v1/projects?page[size]=10&page[number]=5",

    "first": "https://myhost/polarion/rest/v1/projects?page[size]=10&page[number]=1",

    "prev": "https://myhost/polarion/rest/v1/projects?page[size]=10&page[number]=4",

    "next": "https://myhost/polarion/rest/v1/projects?page[size]=10&page[number]=6",

    "last": "https://myhost/polarion/rest/v1/projects?page[size]=10&page[number]=9"

  }

If the result is longer than one page, the response also contains information about the total size, for example:

"meta": {

    "totalCount": 198

  }

If all the requested resources fit on one page, then all resources are returned, the meta.totalCount information is not present, and only the relevant pagination links are included.

Pagination stability¶

There is no session context when paginating, each request is handled independently. That means that if the result set has changed between the requests (for example a new Work Item has been created that matches the query), the pages may overlap or may skip a resource.

As a workaround, we recommend using the revision URL parameter to pinpoint a particular data revision for example when paginating, so as to list all comments or all attachments of a resource:

https://myhost/polarion/rest/v1/projects/myProject/workitems/WI-123/comments?revision=556&page[number]=2

We also recommend using the sort URL parameter for resources that support it. Unsorted query results are displayed in a random order, which means that different pages can return the same data, or that some data can be missing.

Limit of returned relationships¶

The list of related resources displayed in the Relationships section of each resource can potentially contain a lot of items. Their number is automatically reduced to a limit set by the com.siemens.polarion.rest.maxRelationshipSize system property. See Advanced configuration for additional details.

If the limit caused a truncation of the list of related resources, the respective relationship's section also includes information about the total size of the list, for example:

"meta": {

    "totalCount": 1211

  }

If the relationship size does not exceed the limit, the meta.totalCount information is not present.

The relationships representing dependent resources (like comments or attachments) always contain a link.related member pointing to their endpoint. This supports pagination and can be used to retrieve the full set of related resources.

Other relationships (like assignees or categories) do not provide a possibility to work around the limit at the moment, but the default value should be enough for the typical use cases.

Limit of included resources¶

When using the Include feature described in the Includes section, the set of resources returned in the Included section is cut if their number exceeds a limit. This limit is set by the com.siemens.polarion.rest.maxIncludedSize system property, see Advanced configuration for details.

If Included is truncated, the primary response code is not affected (it might still be 200 OK), but the top-level meta section contains an error entry informing about the cut. For example:

"meta": {

  "errors": [ {

    "status": 400,

    "title": "Bad Request",

    "detail": "The number of included resources was more than the configured limit of 500.",

    "source": {

      "parameter": "include"

    }

  } ]

}

Querying¶

The query URL parameter is available for selected endpoints.

The query syntax is the same as in Polarion Java APIs: click Convert to Text to obtain the clear text form of the query criteria for the query URL parameter for the query pane of the respective object type in the Polarion UI.

Query Work Items¶

You can query Work Items on two levels: The Project level and Global levels.

The parameters and the response syntax are the same in both cases:

GET /projects/{projectId}/workitems is the endpoint for project-level querying.

It only returns Work Items that match the query in the given project.

GET /all/workitems is the endpoint for global, repository-level querying.

It returns matching Work Items in any of the projects that the currently authenticated user has read access to.

In the following example, only those resources (Work Items) are returned in the response body that are matching the query criteria in the request URL (the URL parameter is query=type:systemrequirement AND status:reviewed).

• Example Request:

  GET https://myhost/polarion/rest/v1/projects/myProject/workitems?query=type:systemrequirement AND status:reviewed

• Request Body:

Not applicable (N/A)

• Response Body:

{
  "links": {
    "self": "https://myhost/polarion/rest/v1/projects/myProject/workitems?query=type%3Asystemrequirement%20AND%20status%3Areviewed",
    "portal": "https://myhost/polarion/redirect/project/myProject/workitems?query=type%3Asystemrequirement%20AND%20status%3Areviewed"
  },
  "data": [
    {
      "type": "workitems",
      "id": "myProject/WI-123",
      "links": {
        "self": "https://myhost/polarion/rest/v1/projects/myProject/workitems/WI-123",
        "portal": "https://myhost/polarion/redirect/project/myProject/workitem?id=WI-123"
      }
    }
  ]
}

Query Projects¶

When querying Projects, the endpoint is GET /projects.

In the following example, only those resources (Projects) are returned in the response body that are matching the query criteria in the request URL (the URL parameter is query=trackerPrefix:PREFIX AND name:myName_* AND start:[20210401 TO 20210630]). To make all project-related fields visible in the response body, the fields[projects]=@all (sparse fields) URL parameter was also used.

• Example Request:

  GET https://myhost/polarion/rest/v1/projects?fields[projects]=@all&query=trackerPrefix:PREFIX AND name:myName_* AND start:[20210401 TO 20210630]

• Request Body:

Not applicable (N/A)

• Response Body:

{
  "links": {
    "self": "https://myhost/polarion/rest/v1/projects?fields%5Bprojects%5D=%40all&query=trackerPrefix%3APREFIX%20AND%20name%3AmyName_%2A%20AND%20start%3A%5B20210401%20TO%2020210630%5D"
  },
  "data": [
    {
      "type": "projects",
      "id": "myName_tfs_defect",
      "attributes": {
        "id": "myName_tfs_defect",
        "name": "myName_tfs_defect",
        "description": {
          "type": "text/plain",
          "value": "This text comes from the project's Description"
        },
        "active": true,
        "start": "2021-06-02",
        "trackerPrefix": "PREFIX"
      },
      "relationships": {
        "lead": {
          "data": {
            "type": "users",
            "id": "myName"
          }
        }
      },
      "links": {
        "self": "https://myhost/polarion/rest/v1/projects/zskm9k_tfs_defect"
      }
    }
  ]
}

Sorting¶

The SORT URL parameter is available for selected endpoints. The syntax is the same as in Polarion URL (the same parameter value can be seen in the portal link and in the request URL, but the parameter name is sort vs. sorting).

sort=~[sort field]: Resources are sorted in DESCENDING order.

sort=[sort field]: Resources are sorted in ASCENDING order.

sort=~[sort field 1] [sort field 2]: Resources are first sorted by the first criterion (descending), then by the second criterion (ascending).

The separator between two or more sort criteria is a SPACE.

Sort Work Items¶

When sorting Work Items, the endpoint is GET /projects/{projectId}/workitems.

In the following example, the returned resources (Work Items) in the Response Body are sorted into descending order based on the date they were created (the URL parameter is sort=~created).

The most recent Work Items are listed at the top.

• Example Request:

  https://myhost/polarion/rest/v1/projects/myProject/workitems?sort=~created

• Request Body:

Not applicable (N/A)

• Response Body:

{
  "links": {
    "self": "https://myhost/polarion/rest/v1/projects/myProject/workitems?sort=~created",
    "portal": "https://myhost/polarion/redirect/project/myProject/workitems?sorting=~created"
  },
  "data": [
    {
      "type": "workitems",
      "id": "myProject/WI-123",
      "links": {
        "self": "https://myhost/polarion/rest/v1/projects/myProject/workitems/WI-123",
        "portal": "https://myhost/polarion/redirect/project/myProject/workitem?id=WI-123"
      }
    },
...
  ],
  "meta": {
    "totalCount": 20
  }
}

Revisions¶

The revision URL parameter retrieves the HEAD or a specific REVISION of a resource. It is available for selected endpoints. (Generally single-resource endpoints and endpoints listing their child resources.)

For example, workitems/id, workitems/id/comments.

Get a Document from a revision¶

Description: In this example, the resource (Document) returned in the response body represents its state for a specific revision (URL parameter revision=15357). To make specific Document fields visible in the response body, the URL parameter fields[documents]=title,type,status (sparse fields) was also used.

• Example Request:

  GET https://myhost/polarion/rest/v1/projects/myProject/spaces/_default/documents/myLiveDoc?fields[documents]=title,type,status&revision=15357

• Request Body:

Not applicable (N/A)

• Response Body:

{
    "links": {
        "self": 
        "https://myhost/polarion/rest/v1/projects/myProject/spaces/_default/documents/myLiveDoc?fields%5Bdocuments%5D=title%2Ctype%2Cstatus&revision=15357"
    },
    "data": {
        "type": "documents",
        "id": "myProject/_default/myLiveDoc",
        "revision": "15357",
        "attributes": {
            "title": "myLiveDoc",
            "type": "generic",
            "status": "published"
        },
        "links": {
            "self": 
            "https://myhost/polarion/rest/v1/projects/myProject/spaces/_default/documents/myLiveDoc?revision=15357"
        }
    }
}

Get linked Work Items for a Work Item from a revision¶

• Example Request:

  GET https://myhost/polarion/rest/v1/projects/myProject/workitems/WI-123/linkedworkitems?revision=15367

• Request Body:

Not applicable (N/A)

• Response Body:

{
    "links": {
        "self": "https://myhost/polarion/rest/v1/projects/myProject/workitems/WI-123/linkedworkitems?revision=15367"
    },
    "data": [
      {
        "type": "linkedworkitems",
        "id": "myProject/WI-123/parent/myProject/WI-122",
        "revision": "15367",
        "links": {
            "self": "https://myhost/polarion/rest/v1/projects/myProject/workitems/WI-123/linkedworkitems/parent/myProject/WI-122?revision=15367"
        }
    }
  ]
}