Skip to main content

API

Port's API is a generic interface to model your software catalog, ingest data, invoke actions, query scorecards and more.

๐Ÿ’ก Common Port API usageโ€‹

Since Port API is a generic interface, anything that can be done with Port is possible through the API, for example:

  • Update the software catalog using a script;
  • Import your existing asset inventory from a CSV file;
  • Integrate Port with your custom CI/CD;
  • Report the status of a running CI job;
  • Update the software catalog about a new build version for a microservice;
  • Get existing data from your software catalog.

Get API Tokenโ€‹

In order to interact with the API you will need an API token.

Getting an API token involves 2 steps:

  1. Finding your Port API credentials;
  2. Making an API request to generate a valid token.

Find your Port credentialsโ€‹

To find your Port API credentials go to Port, hover on the 3 dots button at the top right corner, select Credentials and then you will be able to view and copy your CLIENT_ID and CLIENT_SECRET:

Generate an API tokenโ€‹

Here are some code examples showing how to generate an API token in various programming languages:

# Dependencies to install:
# $ python -m pip install requests

import requests

CLIENT_ID = 'YOUR_CLIENT_ID'
CLIENT_SECRET = 'YOUR_CLIENT_SECRET'

API_URL = 'https://api.getport.io/v1'

credentials = {'clientId': CLIENT_ID, 'clientSecret': CLIENT_SECRET}

token_response = requests.post(f'{API_URL}/auth/access_token', json=credentials)

access_token = token_response.json()['accessToken']

# You can now use the value in access_token when making further requests

Ingest data via APIโ€‹

Since Port is API-first it is possible to create and update entities using simple REST calls from any platform you use.

Setupโ€‹

To use Port's REST API you need to perform the following steps:

  1. Find your Port credentials;
  2. Save them as secrets or in some other same manner such that you can reference them in your code or CI/CD flow;
  3. Make sure you have an HTTP-capable client.
    1. For example: cURL, python with the requests package, nodejs with fetch/axios, etc.

Usageโ€‹

Since you are using Port's REST API directly, any method that the API provides is at your disposal.

We will focus on three specific use cases:

  • Get catalog entities - available by making HTTP GET requests to https://api.getport.io/v1/blueprints/{blueprint_identifier}/entities/{entity_identifier}, receives the identifier of an existing entity and retrieves it for use in your CI;
  • Create/Update catalog entities - available by making HTTP POST requests to https://api.getport.io/v1/blueprints/{blueprint_identifier}/entities/, receives the identifier and other properties of a new entity or an entity that needs to be updated;
  • Delete catalog entities - available by making HTTP DELETE requests to https://api.getport.io/v1/blueprints/{blueprint_identifier}/entities/{entity_identifier}, receives the identifier of an existing entity and deletes it.
# Dependencies to install:
# $ python -m pip install requests

import requests

CLIENT_ID = 'YOUR_CLIENT_ID'
CLIENT_SECRET = 'YOUR_CLIENT_SECRET'

API_URL = 'https://api.getport.io/v1'

credentials = {'clientId': CLIENT_ID, 'clientSecret': CLIENT_SECRET}

token_response = requests.post(f'{API_URL}/auth/access_token', json=credentials)

access_token = token_response.json()['accessToken']

# You can now use the value in access_token when making further requests

headers = {
'Authorization': f'Bearer {access_token}'
}

blueprint_id = 'MY_BLUEPRINT'
entity_id = 'MY_ENTITY_IDENTIFIER'

response = requests.get(f'{API_URL}/blueprints/{blueprint_id}/entities/{entity_id}', headers=headers)

# response.json() contains the content of the resulting entity