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.

You can also use our GraphQL API when building custom reports.

📘

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

To work with resources that are not related to Fact Sheets, use our REST APIs.

GraphQL Basics

To learn the basics of GraphQL, read our guides:

• GraphQL Basics: Understand how queries and mutations work.
• GraphQL in 10 Minutes: Watch videos to learn the advantages of GraphQL.
• GraphQL with Python: Learn how to use Python to access the GraphQL interface.

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 execute API requests and explore the GraphQL schema.

To open the GraphiQL tool:

1. On the user menu, select Administration.
2. Under Discovery & Integrations, select Developer Tools, and then select GraphiQL.

In the GraphiQL tool, you can:

• Interactively develop and test queries and mutations
• View your request history
• Set up query variables
• View the GraphQL schema

GraphQL Schema

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

You can explore the schema of your Workspace in the GraphiQL tool, in the Documentation Explorer section located on the right side of the page. If the section is hidden, click Docs to expand it.

In the Documentation Explorer, you can:

• View a list of available queries and mutations
• Search for specific queries and mutations

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

Authentication

When using the GraphiQL tool in your Workspace, you don't need to additionally authenticate. The tool automatically handles authentication for you.

When using other API tools, you need to authenticate your requests with an access token. To learn more, see Authentication to LeanIX APIs.

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 Fact Sheets.

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:
  • Querying Data for Custom Reports
  • Tables with Custom Reports

Scripts

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

• Update Costs
• Import Metrics
• Create Resources