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 appropriateAccept 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/jsonJSON 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 theinclude 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
Multiplefilter 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>
}
}
}