​Introduction to Harness GraphQL API

Updated 3 days ago by Archana Singh

GraphQL is a query language for your API, and a server-side runtime for executing queries by using a type system you define for your data. GraphQL isn't tied to any specific database or storage engine and is instead backed by your existing code and data. For more information, visit GraphQL.org and GitHub GraphQL API v4.

Harness exposes its public API in GraphQL format. Virtually all of Harness' meaningful entities are exposed through the API, such as Applications, Services, Artifacts, Cloud Providers, Environments, Workflows, Pipelines, deployed instances, deployment data, etc.

Harness' public GraphQL API unlocks the Harness Continuous Delivery platform, enabling you to build third-party applications that leverage Harness' power to meet your needs. Your applications' queries can return a rich selection of Harness setup parameters and runtime data.

In this topic:

Why GraphQL

GraphQL offers the following 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.

Harness API Explorer

The Harness API Explorer allows you to construct and perform API queries and see their responses. You can use the Explorer to examine the API's structure, to build and test queries against your data, and to optimize your queries. For more information, see Harness API Explorer.

Fetch Data With Queries

Every GraphQL schema has a root type for both queries and mutations. The query type defines GraphQL operations that retrieve data from the server. GraphQL queries return only the data you specify. To form a query, you must specify fields within fields (also known as nested subfields).

Here is an example:

query {
applicationByName(name: "Harness GraphQL"){
id
name
}
}

For more information, see Queries and Schema and Types.

Write Data With Mutations

Every GraphQL schema has a root type for both queries and mutations. The mutation type defines GraphQL operations that change data on the server. It is analogous to performing HTTP verbs such as POSTPATCH, and DELETE.

There are generally three kinds of mutations:

  • creating new data
  • updating existing data
  • deleting existing data

Mutations follow the same syntactical structure as queries, but they always need to start with the mutation keyword. 

Here is an example:

mutation createapp($app: CreateApplicationInput!) {
createApplication(input: $app) {
clientMutationId
application {
name
id
}
}
}

For more information, see Mutations and Schema and Types.

Use clientMutationId (Optional)

This is a unique identifier (string) for the client performing the mutation.clientMutationId appears in both input and output types for mutations.

If present, the same value is intended to be returned in the response as well. The client can use this to indicate duplicate mutation requests to the server and avoid multiple updates for the same request.

This is helpful in the race conditions where the client fires a duplicate request. The original request times out, but the server had processed the original.

This is also required by some of the GraphQL clients like a relay.

Variables

GraphQL has a first-class way to factor dynamic values out of the query, and pass them as a separate dictionary. These values are called variables.

Here is an example:

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

Pagination

Sometimes, API provides a large amount of information for developers to consume. In such a case, the API will paginate the requested items. Here is an example:

{
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.

For more information, see Pagination.

Nodes and IDs

Where a query returns a list of multiple objects, each returned object is treated as a GraphQL node. Several of the above sample queries use nodes sub-elements to reference, or iterate through, individual objects in your results. Here is an example:

 nodes {
id
name
description
createdAt
}

Schema

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.

The ! following the type means that this field is required.

The Harness API's schema includes fields representing the following Harness entities. Use the API Explorer's search box to discover the available fields and their usage. For more information, see API Schema and Structure.

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.

Build Applications

You can use Postman (version 7.2 or higher) to run a GraphQL query, to use APIs in a web app, and to automatically regenerate your query in any programming language that Postman supports. For more information, see Building Applications Using Postman.

API in Beta

API in beta allows you to try out new APIs and changes to the existing API methods before they become part of the official Harness GraphQL API.

During the beta phase, some changes might be made to the features based on the feedback.

Feedback?

You can send us feedback on our APIs at api-feedback@harness.io. We'd love to hear from you.

Next Steps


How did we do?