GraphQL API

Get started with the LeanIX GraphQL API.

Overview

GraphQL is a query language for APIs that allows clients to request precisely the data they need. It was developed by Facebook to provide a more efficient and flexible alternative to traditional REST APIs. To learn more about GraphQL, visit the GraphQL site.

The LeanIX GraphQL API allows you to work with your Fact Sheets and related data. You can retrieve and manipulate Fact Sheets data using GraphQL queries and mutations. To explore more examples, see Use Cases.

The LeanIX GraphQL API adheres to the October 2021 specification for GraphQL.

GraphQL Basics

To learn the basics of GraphQL, see the following:

For comprehensive information about GraphQL, refer to the GraphQL documentation.

Benefits of GraphQL

GraphQL has several benefits, such as:

  • You can summarize required related data in a single request. This allows you to focus on the business logic instead of combining call results and handling different transactions.
  • For large volumes of data, such as in reports or analytics, GraphQL significantly increases performance. You can transfer exactly the attributes that you need through the network, without extra latency.
  • The GraphQL schema is strongly typed. It's an advantage because strong typing implies that the API is largely self-documented. You can see what the immediate response to the query will be. The schema provides descriptions for all API components, making it easier for the user to navigate the reference documentation.
  • Because everything in GraphQL is schema-driven, it's easy to extend an API. You can add new fields or types without affecting existing ones.
  • In GraphQL, the @deprecated annotation is used to mark a field or type as deprecated. This eliminates the need for versioning an API.

GraphiQL Tool

The GraphiQL tool in your workspace allows you to explore the GraphQL schema and interactively develop and test queries.

As an administrator, you can open the tool from your workspace. Follow these steps:

  1. On the user menu, select Administration.
  2. In the sidebar, select Developer Tools, and then select GraphiQL.
Navigating to the GraphiQL Tool from the Developer Tools Page

Navigating to the GraphiQL Tool from the Developer Tools Page

In the GraphiQL tool, you can:

  • Create and execute queries in the interactive Query Editor. To define variables for a query, enter them in the Variables section in JSON format.
  • View the GraphQL schema. To open the schema, in the sidebar on the left, click Show Documentation Explorer.
  • View your request history and open your previous requests. To expand the History section, in the sidebar, click Show History. You can delete specific or all entries, add requests to favorites, and edit the request labels.
  • Interactively create queries and mutations in the Explorer section. To expand the section, in the sidebar, click Show GraphiQL Explorer. Here, you can:
    • Select queries and mutations that you want to add to the Query Editor
    • View and select available attributes for each query and mutation, without having to navigate to the GraphQL schema
    • Duplicate, rename, and delete queries and mutations
Creating Queries Using the Explorer in the GraphiQL Tool

Creating Queries Using the Explorer in the GraphiQL Tool

GraphQL Schema

A GraphQL schema defines the structure and capabilities of a GraphQL API.

You can explore the GraphQL schema in the Docs section in the GraphiQL tool. To expand the section, in the sidebar on the left, click Show Documentation Explorer.

Documentation Explorer in the GraphiQL Tool

Documentation Explorer in the GraphiQL Tool

To reload the GraphQL schema, in the sidebar, click Re-fetch GraphQL schema.

In the Docs section, you can:

  • View a list of available queries and mutations
  • Search for specific queries, mutations, fields, arguments, and other API elements

In the specification, required attributes are marked with an exclamation mark.

Retrieving the GraphQL Schema Metadata

To retrieve the GraphQL schema metadata, use the following query.

query {
  __schema {
    types {
      name
      kind
      interfaces {
        kind
        name
      }
      fields {
        name
      }
      inputFields {
        name
        defaultValue
      }
    }
    queryType {
      name
    }
  }
}

Authentication

To authenticate your requests to the GraphQL API, you need an access token. For more information, see Authentication to LeanIX Services.

When using the GraphiQL tool in your workspace, you don't need to authenticate.

GraphQL API Endpoints

Endpoint for standard GraphQL requests:

https://{SUBDOMAIN}.leanix.net/services/pathfinder/v1/graphql

Endpoint for GraphQL file uploads:

https://{SUBDOMAIN}.leanix.net/services/pathfinder/v1/graphql/upload

Use Cases

With our GraphQL API, you can complete various tasks, such as:

  • Retrieve a single Fact Sheet or a list of Fact Sheets
  • Retrieve Applications with specific attributes
  • Manage relations between Fact Sheets
  • Update specific attributes on Fact Sheets
  • Fetch data from your workspaces to build custom reports

To view example use cases, see the guides in the Fact Sheets section.

Best Practices

Here are some best practices for using GraphQL:

  • Focus on queries and mutations that are one-off in nature or for which you don't need to regularly (such as monthly or weekly) get up-to-date information.
  • Use queries to pull relatively simple information. While you can run complex queries, there are other alternative tools that you can leverage. For example, the Integration API may be an easier and more flexible choice for some use cases. Due to a complexity limit in GraphQL, long queries are denied to prevent possible Denial of Service (DOS) attacks.
  • When you query a large number of Fact Sheets, use pagination. To learn more, see Pagination.
  • Use GraphQL when building custom reports. GraphQL allows you to pull information presented in charts and other visual formats from your workspace. You can find examples of using GraphQL for custom reports in these guides:

Scripts

You can find scripts that use GraphQL in our public LeanIX GitHub repository. Here are some examples: