Harness API

Updated 2 months ago by Michael Katz

Our public GraphQL API unlocks the Harness Continuous Delivery platform, enabling you to build third-party applications that leverage Harness' power to meet your needs. This topic gets you started with our API by covering:

Intended Audience

  • Developers
  • Account Administrators
  • DevOps

Harness Your Way

Using our public API, you can build applications that customize Harness' power to suit your organization's (or your customers') needs. Your applications' queries can return a rich selection of Harness setup parameters and runtime data.

Virtually all of Harness' meaningful entities are exposed through the API: Applications, Services, artifacts, Cloud Providers, Environments, Workflows, Pipelines, deployed instances, deployment data, etc.

Why GraphQL

Harness exposes its public API in GraphQL format. GraphQL offers these efficiency and reliability features for your consuming applications:

  • Scoping – Each request can query for all the resources and data you want, and only the data you want.
  • Introspection – Your client applications can query the API schema for details about the API.
  • Hierarchical Organization – Your queries' nested fields mirror the organization of the JSON data that the queries return.
  • Strong Typing – Applications can specify expected data types per field, and receive clear and specific error notifications.
  • Future-Proofing – GraphQL allows us to incrementally expose new fields and types, and retire obsolete fields, without versioning the API or breaking your existing queries.

For comparisons of GraphQL to REST, and for related resources, please see Facebook's GraphQL.org site (which includes links to client libraries) and GitHub's v4 API orientation.

API Explorer

Harness' API is largely self-documenting. You can use the Harness API Explorer to examine the API's structure, to build and test queries against your data, and to optimize your queries.

The Harness API Explorer is intended primarily as a testing tool. When you're ready to build your queries into working code, see Building Applications below.

To get started: In Harness Manager, select Setup > Harness API Explorer.

This displays the Harness API Explorer shown below.

Harness' API Explorer is based on the GraphiQL IDE. For general instructions on using this GraphiQL explorer, please see GitHub's documentation.

You're now ready to query the API.

Querying the API

Curious to see what kinds of data your applications can obtain? You can easily explore the API schema's nested fields and properties, using these options:

Use Our Sample Queries

Adapt one of the sample queries below into the API Explorer's query pane, and click Run. (Click highlighted keywords to link to descriptions in the right Documentation Explorer pane.)

Traverse or Search the Schema

Click Query in the Documentation Explorer pane to see top-level API objects. Or, type field or property names into the Documentation Explorer's search box to see child properties.

Authentication

Your authentication determines what data you can query and retrieve via the API. By default, when you open the API Explorer, you authenticate using a session key:

Authenticating with an alternative key can provide access to a different scope of data.

Switch Keys (Administrators)

Members of your Account Administrator User Group can use the Authentication drop-down list to select a different API key from your Harness account:

Enter Keys (Non-Administrators)

Non-administrators (with appropriate access) can authenticate using an alternative API key as follows:

  1. Obtain the key from your organization, and copy it to your clipboard, as outlined in API Keys.
  2. In the API Explorer, select Authentication > Use API Key:
  3. In the resulting dialog, paste the key from your clipboard into the API Key field:
  4. Click SUBMIT. The key is now active, and is displayed in the Authentication drop-down.
To query the Harness API in your custom applications, your working code must pass an appropriate API Key from your Harness account as an x-api-key header. See Building Applications, below.

Building Applications

This section outlines how to use Postman (version 7.2 or higher) to run a GraphQL query, and to automatically regenerate your query in any programming language that Postman supports.

Query Harness GraphQL in Postman

This section shows how to transfer a GraphQL query from the Harness API Explorer to Postman. You'll copy and paste your Harness account ID, API Key, and the query itself.

  1. Copy your Harness account ID from your browser's address bar.
  2. In Postman, set up a POST request of this form, ending in your Harness account ID: https://app.harness.io/gateway/api/graphql?accountId=<your-harness-account-id>
  3. Select Postman's Authorization tab.
  4. Set the Type drop-down to API Key.
  5. In the resulting right panel, set the Key to x-api-key.
  6. From Harness Manager, copy your API key's value to your clipboard, as outlined in API Keys.
  7. In Postman's right panel, paste this value into the Value field. (Accept the Add to: Header default.)

    Your Postman setup will now look something like this:
  8. In the Harness API Explorer, click COPY to grab your query.
  9. In Postman, select the Body tab > GraphQL radio button.
  10. Paste your query into Postman's QUERY box.
  11. Click Send to run the query. Verify the response in the response Body panel below.

Build Language-Specific Queries in Postman

Here is how to convert your query into your programming language of choice. We assume that you've already pasted your GraphQL query into Postman's QUERY box.

  1. In Postman, select the raw radio button (not the GraphQL radio button).
  2. Select Postman's Code tab.
  3. In the resulting GENERATE CODE SNIPPETS window, select your target language from the drop-down at upper left. This displays the generated snippet for that language.
  4. Click Copy to Clipboard.
  5. Paste and verify the translated query in your chosen environment.

API Schema and Structure

Harness' schema determines what parameters your queries can specify as arguments, and what data we can return.

Following GraphQL conventions, we represent our schema in terms of fields, types, enums, nodes, edges, and connections. Where a ! character appears at the end of a parameter's name, this indicates a required parameter.

For details about GraphQL's structure and conventions, please see Facebook's and GitHub's GraphQL overviews.

Fields

The Harness API's schema includes fields representing the following Harness entities. Note that many of these <entityId> or <entity> fields are also transformed within the schema into an <entity>Aggregation, <entity>Connection, and/or <entity>Filter. Use the API Explorer's search box to discover the available fields and their usage.

Field Name

Harness Entity/Notes

applicationId

Harness Application.

serviceId

Harness Service.

environmentId

Harness Environment.

workflowId

Harness Workflow.

pipelineId

Harness Pipeline.

executionId

A Harness deployment (execution).

artifactId

Artifact deployed via Harness.

cloudProviderId

Cloud Provider configured in Harness.

Instance

Instance deployed via Harness.

connectorId

Connector configured in Harness.

description

Description of a Workflow, Pipeline, etc.

id

Unique ID of a Harness entity.

name

Name of a Workflow, Pipeline, etc.

total

Total number of a parent Harness entity.

status, ExecutionStatus

Deployment's execution status.

createdAt

Time when deployment was queued in Harness.

startedAt

Time when deployment's execution began.

TimeSeriesAggregation

Used to group returned statistics (on deployments, instances, etc.) by time.

TriggerFilter

One or more Harness Triggers.

limit

Pagination throttler.

offset

Pagination pointer.

Sample Queries

The following examples show some common queries that your applications can execute against the Harness API.

Fetch the List of Services for a Given Application

This sample queries by applicationId to return id and name values for up to 1,000 Services.

{
services(
filters: [
{ application: { operator: EQUALS, values: ["<applicationId>"] } }
]
limit: 1000
) {
pageInfo {
total
}
nodes {
id
name
}
}
}

Show Executions for a Given Workflow

This sample queries by workflowId to return up to 30 deployments.

{
executions(
filters: [
{ workflow: { operator: EQUALS, values: ["<workflowId>"] } }
]
limit: 30
) {
pageInfo {
total
}
nodes {
id
}
}
}

Show Execution Details

This sample retrieves rich details on the parameters and results of (up to) 100 recent executions.

{
executions(limit: 100) {
pageInfo {
limit
offset
total
}
nodes {
id
application {
id
name
}
status
cause {
... on ExecutedByUser {
user {
email
}
}
... on ExecutedByTrigger {
trigger {
id
name
}
}
}
... on PipelineExecution {
pipeline {
id
name
}
}
... on WorkflowExecution {
workflow {
id
name
}
outcomes{
nodes{
... on DeploymentOutcome{
service{
id
name
}
environment{
id
name
}
}
}
}

}
}
}
}

Fetch a list of Pipelines

This example iterates through Pipelines—using specified limit and offsetvalues—to return basic details.

{
pipelines(limit: 20, offset: 20) {
nodes {
id
name
description
createdAt
}
pageInfo {
total
}
}
}

Show Details about a Pipeline

This example returns basic information about a specified Pipeline. It corresponds to a GET operation in a REST API.

{
pipeline(pipelineId: "<pipelineId>") {
id
name
description
}
}

Show Deployments for a Given Pipeline

This sample queries by pipelineId to return details on up to 3 deployments.

{
executions(
filters: [{ pipeline: { operator: EQUALS, values: ["<pipelineId>"] } }]
limit: 3
) {
pageInfo {
total
}
nodes {
id
}
}
}

Show Pipelines for a Given Application

This sample queries by applicationId to return details about corresponding Pipelines.

{
pipelines(
filters: [
{ application: { operator: EQUALS, values: ["<ApplicationID>"] } }
]
limit: 5
offset: 2
) {
nodes {
id
name
description
createdAt
}
pageInfo {
total
}
}
}

Show Services for a Given Application

This nested query by applicationId returns the names of the specified Application's contained Services.

{
application(applicationId:"<applicationId>") {
services(limit:100, offset:0) {
pageInfo{
total
}
nodes{
name
}
}
}
}

Paginating Results

Several sample queries above specify pagination for large result sets. Here's a simplified excerpt:

{
pipelines(
...
limit: 5
offset: 2
)
...

You can specify pagination criteria as follows:

  • limit is a throttler, specifying how many results to return per page.
  • offset is an index from 0.

Query Variables

Using the Harness API Explorer, you can test the use of variables for your production code. Define your variables in the API Explorer's QUERY VARIABLES pane, and call them in the query pane.

As a simple example, here is a revision of the Show Details about a Pipeline sample query above. Here, we pass the required pipelineId argument as a variable named $thisPipeline:

Here is the revised query, incorporating the new variable:

query($thisPipeline: String!) {
pipeline(pipelineId: $thisPipeline) {
id
name
description
}
}

Here is the format for passing the value in the QUERY VARIABLES pane:

{
"thisPipeline": "<pipelineId>"
}

For background information on query variables, see GraphQL.org's Queries and Mutations documentation. For details about the syntax shown above, see GraphQL.org's How to Pass Variables in GraphiQL Quick Tip.

Rate/Data Limiting

The Harness API imposes a (sliding-window) rate limit of 30 requests per minute, per account. Each request is limited to a maximum query depth of 10 properties. Harness reserves the right to change these limits, in order to optimize performance for all API consumers.

Next Steps


How did we do?