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 SAP 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 SAP LeanIX GraphQL API adheres to the October 2021 specification for GraphQL.

GraphQL Basics

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.

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.

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

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.

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 SAP 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 explore more examples, see Example Queries and Mutations.

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. To view examples of using GraphQL with custom reports, see Using GraphQL Queries with Custom Reports.

Scripts

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

• Update Costs
• Import Metrics
• Create Resources