Stellate Public API

Stellate has a public API where you can query data around your organization(s) and service(s).

Usage

To use the public API, you must create a user token first. Head to your Access Tokens  page, click the Create a token button, and name the new token. Make sure also to copy the token to a safe place; you won’t be able to see it again.

With the token, you’re now all set to visit graph.stellate.co .

To configure your access token, open the Headers tab, and add the following snippet, replacing {user-token}, with the token, you created earlier.

{
  "Authorization": "Bearer {user-token}"
}

With this done, let’s start exploring the API. For example, you can get all your organizations and their services by running the following query.

query {
  organizations {
    edges {
      node {
        id
        name
      }
    }
  }
}

You can explore more queries via the public playground  or browse through the API Documentation .

Complexity limits

To help insure the reliability of our API we enforce a limit on the complexity of queries that can be resolved. The complexity of a query is calculated as an estimate of the maximum number of nodes a query return.

The complexity limit is currently set at 1000 nodes during our early access period while we evaluate how our API is used, and may be adjusted over time to support additional use cases, and ensure stability for all users.

The complexity of a query is calculated by counting the number of nodes a query might return. Each field that returns an object, union, or interface, will be considered to have a complexity of 1. For list fields (and connections) the complexity of nested selections will be multiplied by the expected size of the list. Connections will use the values of the first or last argument. For lists without arguments that specify their size, a default size of 20 is assumed. If you are running into complexity limits, you can try specifying a smaller size for fields that return connections or lists, allowing you to have a more complex nested selection.

For example the following query exceeds the current complexity limit:

query {
  organizations {
    edges {
      node {
        services {
          edges {
            node {
              id
            }
          }
        }
      }
    }
  }
}

We can reduce the number of edges returned by our connections to reduce the complexity and allow our queries to succeed:

query {
  organizations(first: 10) {
    edges {
      node {
        services(first: 10) {
          edges {
            node {
              id
            }
          }
        }
      }
    }
  }
}

API Errors

When interacting with APIs its is always good practice to understand how things can fail. In our API errors will be returned as part of the JSON response under the "errors" key:

{
  "errors": [
    {
      "message": "No auth token provided",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": ["service"],
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ]
}

Errors in API responses will generally have 4 properties:

• "message": This is a human readable message letting you know what went wrong
• "location": This is the line/column of the part of the query this error is associated with
• "path": This is the path to the field in the response that could not be loaded because of this error
• "extensions": This is an object containing additional information about the error

The "extensions" field will contain a "code" property that can be used to classify the type of error. Generally this error code should be used instead of parsing the error message when handling specific types of errors. See potential error codes:

UNAUTHENTICATED

The request does not contain a valid form of authentication.

FORBIDDEN

The request includes authentication, but was not authorized to access the requested resource.

NOT_FOUND

The request resource could not be found.

BAD_REQUEST

The inputs for the request were invalid.

GRAPHQL_VALIDATION_FAILED

The request was malformed.

QUERY_COMPLEXITY

The request exceeds the maximum query complexity.

QUERY_DEPTH

The query exceeds the maximum number of fields that can be selected.

QUERY_BREADTH

The query exceeds the maximum depth for nested selections.