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.
To learn the basics of GraphQL, see the following:
- GraphQL Basics: Understand how queries and mutations work.
- Using GraphQL with Python: Learn how to run GraphQL queries and mutations using Python.
- Example Queries and Mutations: View examples and try them out in your workspace.
For comprehensive information about GraphQL, refer to the GraphQL documentation.
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
@deprecatedannotation is used to mark a field or type as deprecated. This eliminates the need for versioning an API.
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:
- On the user menu, select Administration.
- In the sidebar, select Developer Tools, and then select GraphiQL.
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
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.
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.
To retrieve the GraphQL schema metadata, use the following query.
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.
Endpoint for standard GraphQL requests:
Endpoint for GraphQL file uploads:
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.
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:
You can find scripts that use GraphQL in our public LeanIX GitHub repository. Here are some examples: