Retrieving Integration Information

Use the REST API to fetch Integration information including settings and errors

Authenticating

To begin, you will need to authenticate to the Polarity Server to obtain a reusable bearer token that will be used with subsequent authenticated requests.

See Authentication for information on how to authenticate to the Polarity Platform and acquire an authentication token.  The authentication token will be used in all the requests outlined below and is referenced in examples as <AUTH_TOKEN>.

Get Integrations

You can retrieve information about Integrations by using the GET /api/integrations endpoint.  This endpoint will return information about Integrations installed on your server to include running status, Integration option values, and references to any Integration errors.

Examples

CURL

curl -v -X GET \
https://<polarity.server.url>/api/integrations \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/vnd.api+json'

Python

import requests
import json

def get_integrations(token, host):
    url = f'{host}/api/integrations'

    headers = {
        'Content-Type': 'application/vnd.api+json',
        'Authorization': f'Bearer {token}'
    }

    response = requests.request('GET', url, headers=headers)
    response.raise_for_status()

    return response.json()
    
integrations = get_integrations('my-auth-token', 'https://polarity.server.url')    

Replace <POLARITY_HOSTNAME> with the hostname of your Polarity server and <AUTH_TOKEN> with the value of your Bearer token.

Paging

The default page size for the endpoint is 100.  

If you have more than 100 installed Integrations, you will need to increase the page size or page through the results using the page[size] and page[number] query parameters.  The parameter page[size] tells the endpoint the maximum number of results to return, and the parameter page[number] tells the endpoint which page of results to return.

CURL

curl -v -X GET -G \
'https://<polarity.server.url>/api/integrations' \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/vnd.api+json' \
-d page[size]=200 \
-d page[number]=1

Python

import requests
import json

def get_integrations(token, host):
    url = f'{host}/api/integrations'

    params = {
        'page[size]': 200,
        'page[number]': 1
    }
    
    headers = {
        'Content-Type': 'application/vnd.api+json',
        'Authorization': f'Bearer {token}'
    }

    response = requests.request('GET', url, headers=headers, params=params)
    response.raise_for_status()

    return response.json()
    
integrations = get_integrations('my-auth-token', 'https://polarity.server.url')    

Filtering

Integration Status

You can return only Integrations that are running by using the query parameter filter[integration.status]=running.

CURL

curl -v -X GET -G \
'https://<polarity.server.url>/api/integrations' \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/vnd.api+json' \
-d filter[integration.status]=running

Python

import requests
import json

def get_integrations(token, host):
    url = f'{host}/api/integrations'
    params = {
        'filter[integration.status]': 'running'
    }
 
    headers = {
        'Content-Type': 'application/vnd.api+json',
        'Authorization': f'Bearer {token}'
    }

    response = requests.request('GET', url, headers=headers, params=params)
    response.raise_for_status()

    return response.json()
   
integrations = get_integrations('my-auth-token', 'https://polarity.server.url')  

Integration Errors

You can return only Integrations with errors using the filter[integration.integration-errors]=true query parameter.

CURL

curl -v -X GET -G \
'https://<polarity.server.url>/api/integrations' \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/vnd.api+json' \
-d filter[integration.integration-errors]=true

Python

import requests
import json

def get_integrations_with_errors(token, host):
    url = f'{host}/api/integrations'

    params = {
        'filter[integration.integration-errors]': true
    }
    
    headers = {
        'Content-Type': 'application/vnd.api+json',
        'Authorization': f'Bearer {token}'
    }

    response = requests.request('GET', url, headers=headers, params=params)
    response.raise_for_status()

    return response.json()
    
integrations = get_integrations_with_errors('my-auth-token', 'https://polarity.server.url')  

Return Payload Format

The endpoint will return a JSON payload with a list of Integration models as part of a top-level data key.  In addition, there will be a top-level meta key which contains paging information including the page.total attribute which indicates the total number of Integrations that could be returned by the endpoint given the applied filtering.  

Return Data Example

{
  "data": [
     // one or more integration models
   ],
   "meta": {
     "page": {
       "number": 1, // current page number
       "size": 100, // number of integrations returned per page
       "total": 135 // total number of integrations matching the filter criteria
     }
   }
}  

Integration Model

Each Integration model contained within data will have the following structure:

{
  "attributes": {
    // integration model attributes
  },
  "id": "<INTEGRATION_ID>",
  "links": {
    "self": "/api/integrations/<INTEGRATION_ID>"
  },
  "relationships": {
    "integration-errors": {
      "data": [
        // list of integration errors (empty if there are no errors
       ]
      "links": {
        "self": "/api/integration-errors?filter[integration.id]=<INTEGRATION_ID>"
      }
    },
    "integration-options": {
      "data": [
        // list of integration options
      ],
      "links": {
        "self": "/api/integration-options?filter[integration.id]=<INTEGRATION_ID>
      }
  },
  "type": "integrations"
}

Integration Attributes

To view a full list of Integration attributes returned by the fetch Integration endpoints see the Integration Attributes page.

Get Integration Errors

You can fetch all Integration errors using the GET /api/integrations/errors endpoint.  Only Integration managers and Polarity admins are able to view errors for Integrations.

Examples

CURL

curl -v -X GET \
https://<polarity.server.url>/api/integrations/errors \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/vnd.api+json'

Python

import requests
import json

def get_integration_errors(token, host):
    url = f'{host}/api/integrations/errors'

    headers = {
        'Content-Type': 'application/vnd.api+json',
        'Authorization': f'Bearer {token}'
    }

    response = requests.request('GET', url, headers=headers)
    response.raise_for_status()

    return response.json()
    
integration_errors = get_integration_errors('my-auth-token', 'https://polarity.server.url')    

This endpoint does not support paging and will return all available errors. 

Return Payload Format

The errors endpoint will return an array of error models within a top-level data attribute.

{
  "data": [
    // Zero or more error models
  ],
  "jsonapi": {
    "version": "1.0"
  }
}  

Error Model

The error model has the following format:

{
  "attributes": {
    // error attributes
  },
  "id": "<ERROR_ID>",
  "links": {
    "self": "/api/integration/<INTEGRATION_ID>/errors/<ERROR_ID>"
  },
  "relationships": {
    "integration": {
      "data": {
        "id": "<INTEGRATION_ID>"
        "type": "integrations"
      }
    }
  },
  "type": "integration-errors"
}

Error Attributes

Each error model has fixed attributes common to all errors and then also includes a meta-attribute which contains Integration specific error information.