Learn the GraphQL basics. Create and execute your first queries and mutations.
Overview
This page provides an overview of basic GraphQL concepts to help you get started. To learn about GraphQL and how it works, refer to the GraphQL documentation.
To create and test your first queries and mutations, you can use the GraphiQL tool in your workspace.
To explore the GraphQL schema, navigate to the Documentation Explorer section in the GraphiQL tool. In the schema, an exclamation mark next to an attribute indicates that the attribute is required (cannot be null).
Tip
To explore example queries and mutations for the SAP LeanIX GraphQL API, see Example Queries and Mutations.
Queries
GraphQL queries allow you to retrieve data, similar to GET methods in REST APIs. To learn more about queries, see Queries and Mutations in the GraphQL documentation.
To explore queries available within the SAP LeanIX GraphQL API, navigate to the Documentation Explorer section in the GraphiQL tool.
As an example, let's retrieve a Fact Sheet by its ID using the factSheet query. id is a required argument for this query. To get the ID of a Fact Sheet, navigate to the Fact Sheet page in the application user interface and copy the ID from the URL.
In the example, we request the following Fact Sheet attributes to be returned in the response: id, name, and type. You can modify the query to retrieve the data you need.
Example query:
{
factSheet(id: "28fe4aa2-6e46-41a1-a131-72afb3acf256") {
id
name
type
}
}
Example response:
{
"data": {
"factSheet": {
"id": "28fe4aa2-6e46-41a1-a131-72afb3acf256",
"name": "AC Management",
"type": "Application"
}
}
}
Mutations
GraphQL mutations allow you to modify data, similar to POST, PUT, PATCH, and DELETE methods in REST APIs. To learn more about mutations, see Mutations in the GraphQL documentation.
To explore mutations available within the SAP LeanIX GraphQL API, navigate to the Documentation Explorer section in the GraphiQL tool.
As an example, let's create an Application Fact Sheet using the createFactSheet mutation. The fields name and type of the BaseFactSheetInput input argument are required for this mutation. We pass these fields using the $input variable.
To retrieve specific Fact Sheet attributes in the response, use the factSheet query. In the example, we retrieve the following attributes: id, name, and type.
Example mutation with a variable:
mutation ($input: BaseFactSheetInput!) {
createFactSheet(input: $input) {
factSheet {
id
name
type
}
}
}
The mutation requires an $input variable. Define the variable in JSON format.
We recommend using variables in mutations with a large number of input parameters.
Variables:
{
"input":{"name":"New Fact Sheet", "type": "Application"}
}
Alternatively, you can create a mutation without a variable.
Example mutation without a variable:
mutation {
createFactSheet(input: {name: "New Fact Sheet", type: Application}) {
factSheet {
id
name
type
}
}
}
Once you have executed the request, you get a response that contains the details of the new Fact Sheet. The id is generated automatically.
Example response:
{
"data": {
"createFactSheet": {
"factSheet": {
"id": "16fdc1a9-ae59-4d0a-b6ce-bb717baa74f3",
"name": "New Fact Sheet",
"type": "Application"
}
}
}
}
Including Multiple Mutations in a Single Request Using Aliases
To make your program run faster and deal with delays caused by network connection, you can include multiple mutations in one request by using mutation aliases.
When using aliases in mutations, follow these guidelines:
- Choose a unique alias for each mutation.
- Split your mutations into manageable chunks to prevent execution disruption caused by HTTP timeouts. Depending on the complexity of specific mutations, 50 is a reasonable chunk size to start with.
In the example mutation, we create two Application Fact Sheets using mutation aliases fs1 and fs2.
Example mutation:
mutation {
fs1: createFactSheet(input: {name: "fs1", type:Application}) {
factSheet { id }
},
fs2: createFactSheet(input: {name: "fs2", type:Application}) {
factSheet { id }
}
}
Example response:
{
"data": {
"fs1": {
"factSheet": {
"id": "8acea607-94c6-4818-9c64-2af5ecd0be98"
}
},
"fs2": {
"factSheet": {
"id": "6fe9bd88-dd6b-461d-ab35-db139961b48f"
}
}
}
}
Retrieving a List of Filtering Facet Keys
The following example shows how to retrieve a list of all facet keys within a workspace.
Example query:
{
allFactSheets{
filterOptions {
facets {
facetKey
results {
name
key
}
}
}
}
}
Example response:
{
"data": {
"allFactSheets": {
"filterOptions": {
"facets": [
{
"facetKey": "FactSheetTypes",
"results": [
{
"name": "BusinessCapability",
"key": "BusinessCapability"
},
{
"name": "Process",
"key": "Process"
},
{
"name": "UserGroup",
"key": "UserGroup"
},
{
"name": "Project",
"key": "Project"
},
{
"name": "Application",
"key": "Application"
},
{
"name": "Interface",
"key": "Interface"
},
{
"name": "DataObject",
"key": "DataObject"
},
{
"name": "ITComponent",
"key": "ITComponent"
},
{
"name": "Provider",
"key": "Provider"
},
{
"name": "TechnicalStack",
"key": "TechnicalStack"
}
]
},
{
"facetKey": "hierarchyLevel",
"results": [
{
"name": "1",
"key": "1"
},
{
"name": "2",
"key": "2"
},
{
"name": "3",
"key": "3"
}
]
},
{
"facetKey": "DataQuality",
"results": [
{
"name": "noResponsible",
"key": "_noResponsible_"
},
{
"name": "qualitySealBroken",
"key": "_qualitySealBroken_"
},
{
"name": "noDescription",
"key": "_noDescription_"
},
{
"name": "noLifecycle",
"key": "_noLifecycle_"
}
]
},
{
"facetKey": "_TAGS_",
"results": [
{
"name": "Headquarter",
"key": "aa51ccc9-db61-48df-89d1-f217f37757ea"
},
{
"name": "Tag2",
"key": "819d3d4f-f044-470a-8f5d-c11bc15eff67"
}
]
}
]
}
}
},
"errors": null
}
Pagination in GraphQL
The SAP LeanIX GraphQL API employs the concept of Relay Cursor Connections for pagination.
Pagination is done by inserting a cursor for the after argument. For the initial cursor, the empty string can be used (or the argument can be omitted, as in the example above).
The following query returns the first two Fact Sheets from the list.
Example query:
{
allFactSheets(first: 2, after: "") {
edges {
cursor
node {
name
}
}
}
}
Example response:
{
"data": {
"allFactSheets": {
"edges": [
{
"cursor": "bWl4OjA=",
"node": {
"name": "AC Management"
}
},
{
"cursor": "bWl4OjE=",
"node": {
"name": "AC Management Cloud"
}
}
]
}
}
}
You can include the PageInfo object in the request. This object contains information about the paging state:
hasNextPage: Defines whether more pages are available.endCursor: Shows the position of the current paging cursor.
Example query:
{
allFactSheets(first: 2, after: "") {
pageInfo {
hasNextPage
endCursor
}
edges {
cursor
node {
name
}
}
}
}
Example response:
{
"data": {
"allFactSheets": {
"pageInfo": {
"hasNextPage": true,
"endCursor": "bWl4OjEjRFhGMVpYSjVRVzVrUm1WMFkyZ0JBQUFBQUFISUJSb1dPRmhwT0dSWFlYVlNNRU55TlZGSVdYbExTVjlLWnc9PSUxNzA1NTY3MDg3Nzg2"
},
"edges": [
{
"cursor": "bWl4OjA=",
"node": {
"name": "AC Management"
}
},
{
"cursor": "bWl4OjE=",
"node": {
"name": "AC Management Cloud"
}
}
]
}
}
}
To retrieve the next two results, enter the value of endCursor in the argument after.
Example query:
{
allFactSheets(first: 2, after: "bWl4OjEjRFhGMVpYSjVRVzVrUm1WMFkyZ0JBQUFBQUFISUJSb1dPRmhwT0dSWFlYVlNNRU55TlZGSVdYbExTVjlLWnc9PSUxNzA1NTY3MDg3Nzg2") {
pageInfo {
hasNextPage
endCursor
}
edges {
cursor
node {
name
}
}
}
}
Example response:
{
"data": {
"allFactSheets": {
"pageInfo": {
"hasNextPage": true,
"endCursor": "bWl4OjMjRFhGMVpYSjVRVzVrUm1WMFkyZ0JBQUFBQUFISUJoc1dPRmhwT0dSWFlYVlNNRU55TlZGSVdYbExTVjlLWnc9PSUxNzA1NTY3NDI2NDgy"
},
"edges": [
{
"cursor": "bWl4OjI=",
"node": {
"name": "AC Management to HR Admin"
}
},
{
"cursor": "bWl4OjM=",
"node": {
"name": "Accenture"
}
}
]
}
}
}