API Introduction

Note: This platform is renamed Coverity on Polaris. Unless otherwise specified, references to Polaris or Polaris Software Integrity Platform in this documentation are referring to Coverity on Polaris.

Before getting started, it helps to understand the functionality of the various parts of the Polaris API.

This topic covers:
  • MIME types
  • JSON API
  • Filtering
  • Including
  • Paginating
  • Combining query parameters
  • Identifiers
  • Endpoint URNs

API Endpoint MIME Types

Every request must have the appropriate Accept and Content-Type headers. The Polaris API documentation provides the appropriate MIME type for each API endpoint.

JSON API: application/vnd.api+json

JSON: application/json

JSON API

Resources in Polaris are consistent with the JSON API standard. The standard defines a schema for representing application resources and metadata. Query parameters for filtering, paginating, and including related resources are also defined. Multiple filter and includes query parameters can be used in a single request. You can find the standard reference page at https://jsonapi.org/format/.

Filtering Resources

Resources can be filtered by their attributes. The supported filtering operations are:
  • $eq equal, exact match
  • $neq not equal, exact match
  • $substr substring, exact match
  • $isubstr substring, case insensitive

Example: Retrieve all users with the email addressing matching "joe@example.com."

Request:
                $ curl -X GET \
                'https://subdomain.polaris.synopsys.com/api/auth/v1/users?filter[users][email][$eq]=joe@example.com' \
                -H 'Accept: application/vnd.api+json' \
                -H 'Authorization: Bearer {JWT}'
Response:
                {
                "data": [
                {
                "type": "users",
                "id": "string",
                "attributes": {
                "owner": false,
                "automated": false,
                "agreed-to-terms": true,
                "first-time": false,
                "name": "Joe",
                "agreedTermsOfUse": [
                <snip>
                ],
                "enabled": true,
                "email": "joe@example.com",
                "username": "joe",
                "date-created": "YYYY-MM-DDThh:mm:ss.SSS+0000"
                },
                "relationships": {
                <snip>
                },
                "links": {
                <snip>
                }
                }
                ],
                "included": [ ],
                "meta": {
                "limit": 500,
                "offset": 0,
                "total": 1
                }
                }
            
Request:
                $ curl -X GET \
                'https://subdomain.polaris.synopsys.com/api/query/v1/roll-up-counts?branch-id=1e830b51-e1d4-44a5-bcf3-90a258d5d5e8\
                &project-id=d24ec4e9-e6aa-4299-b64c-218f83dc9b62&page[limit]=1&page[offset]=0' \
                -H 'Accept: application/vnd.api+json' \
                -H 'Authorization: Bearer {JWT}'
            
Response:
                {
                "data": [
                {
                "id": "string",
                "type": "count",
                "relationships": {
                "path": {
                "data": {
                "id": "string",
                "type": "path"
                }
                },
                <snip>
                },
                "attributes": {
                "value": 588
                }
                }
                ],
                "included": [
                {
                "id": "string",
                "type": "path",
                "attributes": {
                "path": [],
                "path-type": "directory",
                "is-leaf": false
                }
                }
                ],
                "meta": {
                "offset": 0,
                "limit": 1,
                "total": 1,
                "complete": true,
                "group-by": "path",
                "run-count": 3
                }
                }
            

Including Resources

When resources have relations to other resources; for example, contributors in an organization or branches in a project, you can include relevant results in a response by using the include query parameter. Use multiple separate include query parameters to request multiple related resources.

Example: Include the organization resource to which the user(s) belong.

Request:
                $ curl -X GET \
                'https://subdomain.polaris.synopsys.com/api/auth/v1/users?include[user][]=organization' \
                -H 'Accept: application/vnd.api+json' \
                -H 'Authorization: Bearer {JWT}'
            
Response:
                {
                "data": [
                {
                "type": "users",
                "id": "string",
                "attributes": {
                "owner": false,
                "automated": false,
                "agreed-to-terms": true,
                "first-time": false,
                "name": "joe",
                "agreedTermsOfUse": [
                <snip>
                ],
                "enabled": true,
                "email": "joe@example.com",
                "username": "joe",
                "date-created": "YYYY-MM-DDThh:mm:ss.SSS+0000"
                },
                "relationships": {
                <snip>
                }
                ],
                "included": [
                {
                "type": "organizations",
                "id": "string",
                "attributes": {
                "organizationname": "string",
                "description": "string",
                "soft-deleted": false,
                "password-authentication": {
                "enabled": true,
                "allowSelfSignup": false
                },
                "date-created": "YYYY-MM-DDThh:mm:ss.SSS+0000"
                },
                "relationships": {
                <snip>
                },
                "links": {
                <snip>
                }
                }
                ],
                "meta": {
                "limit": 500,
                "offset": 0,
                "total": 1
                }
                }
            

Paginating Resources

An API endpoint having more than one resource returned should be paginated. Requests the initial page of resources, and then calculates subsequent pages based on the attribute total in the meta-information of the response.

Accepted paging parameters:

  • page[limit] the maximum number of resources to return. One-based.
  • page[offset] the offset, or page, of users to return. The combination of offset and limit should not exceed the maximum number of resources. Zero-based.

Example: Returned resource pagination

Request:
                $ curl -X GET \
                'https://subdomain.polaris.synopsys.com/api/auth/v1/users?page[limit]=25&page[offset]=0' \
                -H 'Accept: application/vnd.api+json' \
                -H 'Authorization: Bearer {JWT}'
            
Response:
                {
                "data": [
                <snip>
                ],
                "meta": {
                "limit": 25,
                "offset": 0,
                "total": 50
                }
                }
            
Request:
                $ curl -X GET \
                'https://subdomain.polaris.synopsys.com/api/auth/v1/users?page[limit]=25&page[offset]=25' \
                -H 'Accept: application/vnd.api+json' \
                -H 'Authorization: Bearer {JWT}'
            
Response:
                {
                "data": [
                <snip>
                ],
                "meta": {
                "limit": 25,
                "offset": 25,
                "total": 50
                }
                }
            

Combining Query Parameters

Multiple filter and include parameters can be combined in a single request.

Example: Receive a list of users with the example.com email domain, in a particular organization, and limit to the first 5 users.

Request:
                $ curl -X GET \
                'https://subdomain.polaris.synopsys.com/api/auth/v1/users?filter[users][email][$isubstr]=example.com\
                &filter[users][organization][id][$eq]=po43drodup4d16jdm3jd4m6ch0&include[users][]=organization\
                &page[limit]=5&page[offset]=0' \
                -H 'Accept: application/vnd.api+json' \
                -H 'Authorization: Bearer {JWT}'
            

Identifiers

Some API endpoints might utilize URNs to identify resources. The format is:

urn:x-swip:<resource name>:<resource id>

URN use in Role Assignments

A role assignment is scoped to a resource. For example, a user can be a contributor for an organization and an administrator for a project. Uniform Resource Names (URNs) are used to identify the resource.

Example: Role assignments currently support the following resource types.

Organizations:
                {
                "data":
                {
                "type": "role-assignments",
                "attributes": {
                "object": "urn:x-swip:organizations:{{orgid}}"
                },
                "relationships": {
                <snip>
                }
                }
                }
            
Projects:
                {
                "data":
                {
                "type": "role-assignments",
                "attributes": {
                "object": "urn:x-swip:projects:{{projectid}}"
                },
                "relationships": {
                <snip>
                }
                }
                }