Migrating from the Fact Sheets REST API to the GraphQL API

Overview

In this migration guide, you can find examples showing how to transition from the LeanIX Fact Sheets REST API to the GraphQL API. To learn more about the deprecation of REST API factSheets endpoints, see Deprecation of REST API Endpoints in Favor of GraphQL.

For each operation that you can perform on Fact Sheets through the API, we provide an example REST call and its equivalent GraphQL query or mutation.

For the REST implementation, the result of an operation may vary depending on the provided parameters. We illustrate requests for each specific parameter with examples, providing a clear path for a seamless migration.

In the following sections are examples for each documented endpoint within the OpenAPI Explorer.

Before You Start

Before you dive into the guide, note the following:

In this guide, we provide examples for the fundamental combinations of existing parameters.
Example queries are basic. They do not contain separate GraphQL variables or pagination parameters. To learn how to work with GraphQL queries and mutations, see GraphQL Basics.
All examples are based on the Fact Sheet type Application. If you want to use a different Fact Sheet type, change the corresponding field.
All queries include placeholders for variables, such as {id} or {toId}. Before you make API requests, replace them with actual values.
As an administrator, you can use the GraphiQL tool in your Workspace to try out the provided examples. To open the tool, in the Administration section, select Developer Tools > GraphiQL.
The examples usually contain simple queries that do not include all possible parameters. If needed, you can include additional parameters in the query.
Following GraphQL best practices, we recommend that you query minimal data to reduce the payload size and response times. For other recommendations, see Best Practices.

Get All Fact Sheets

Method	Path	Reference
GET	`/factSheets`	Schema

In this section, we provide an example of retrieving all Fact Sheets of the Application type and its relations to Fact Sheets of the ITComponent type.

REST call:

https://{SUBDOMAIN}.leanix.net/services/pathfinder/v1/factSheets?relationTypes=relApplicationToITComponent&type=Application

GraphQL query:

query {
  allFactSheets(filter: {responseOptions: {maxFacetDepth: 5}, facetFilters: [
    {facetKey: "FactSheetTypes",
      keys:["Application"],
      operator: OR
    }
  ]}, sort: [{key: "displayName", order: asc}]) {
    totalCount
    edges {
      node {
        id
        displayName
        description
        rev
        type
        permissions {
          create
          read
          update
          delete
          self
        }
        qualitySeal
        lxState
        updatedAt
        completion {
          percentage
        }
        tags {
          id
          name
          description
          color
          tagGroup {
            id
            name
            shortName
            mode
          }
        }
        comments(filter: {status: ACTIVE}) {
          totalCount
          edges {
            node {
              message
            }
          }
        }
        subscriptions(filter: {userId: "{userId}"}) {
          edges {
            node {
              id
              user {
                id
                firstName
                lastName
                email
              }
              type
              roles {
                id
                comment
              }
            }
          }
        }
        status
        level
        category
        ... on Application {
          relApplicationToITComponent {
            edges {
              node {
                factSheet {
                 	id
                  name
                }
              }
            }
          }
        }
      }
    }
  }
}

In the example request, we retrieve all Fact Sheets of the Application type, including their default fields, completion, tags, comments, subscriptions, and more. For related Fact Sheets of the ITComponent type, we only fetch their id and name.

Get a Fact Sheet Hierarchy by Its Root ID

Method	Path	Reference
GET	`/factSheets/hierarchy/{rootId}`	Schema

You can retrieve all Fact Sheets equal to or below a specific root Fact Sheet.

REST call:

https://{SUBDOMAIN}.leanix.net/services/pathfinder/v1/factSheets/hierarchy/{rootId}

GraphQL query:

query {
  allFactSheets(hierarchy: {mode: FULL_TREE} filter: {ids: ["{rootId}"]}) {
    edges {
      node {
        id
        displayName
      }
    }
  }
}

Get a Fact Sheet by Its ID

Method	Path	Reference
GET	`/factSheets/{id}`	Schema

REST call:

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

GraphQL query:

query {
  factSheet(id: "{id}") {
    id
    displayName
    description
    rev
    type
    permissions {
      create
      read
      update
      delete
      self
    }
    qualitySeal
    lxState
    updatedAt
    completion {
      percentage
    }
    tags {
      id
      name
      description
      color
      tagGroup {
        id
        name
        shortName
        mode
      }
    }
    comments(filter: {status: ACTIVE}) {
      totalCount
      edges {
        node {
          message
        }
      }
    }
    subscriptions(filter: {userId: "{userId}"}) {
      edges {
        node {
          id
          user {
            id
            firstName
            lastName
            email
          }
          type
          roles {
            id
            comment
          }
        }
      }
    }
    status
    level
    category
  }
}

To limit the results to only the id and name fields of a Fact Sheet, use the following query:

query {
  factSheet(id:"{id}") {
    id
    name
  }
}

Get All Relations of a Fact Sheet

Method	Path	Reference
GET	`/factSheets/{id}/relations`	Schema

In this section, we retrieve all relations of a Fact Sheet with the specified {id}.

REST call:

https://{SUBDOMAIN}.leanix.net/services/pathfinder/v1/factSheets/{id}/relations

GraphQL query:

query {
  factSheet(id: "{id}") {
    ... on Application {
      relToChild {
        edges {
          node {
            factSheet {
              id
              name
            }
          }
        }
      }
      relApplicationToITComponent {
        edges {
          node {
            factSheet {
              id
              name
            }
          }
        }
      }
      relToSuccessor {
        edges {
          node {
            factSheet {
              id
              name
            }
          }
        }
      }
    }
  }
}

In the example request, we retrieve the following relations of a Fact Sheet: relToChild, relApplicationToITComponent, and relToSuccessor. For the target Fact Sheet, we only fetch the id and name fields.

While the REST endpoint provides all possible fields and data in a single call, GraphQL requires you to add all the required relations and fields of the target Fact Sheet to your query.

Create a Fact Sheet

Method	Path	Reference
POST	`/factSheets`	Schema

REST call:

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

Example request body:

{
  "name": "TestFactSheet",
  "description": "This is a demo fact sheet.",
  "type": "Application"
}

GraphQL mutation:

mutation {
  createFactSheet(input: {
    name: "TestFactSheet"
    type: Application
  }
  patches: [
    {
      op: add
      path: "/description"
      value: "This is a demo fact sheet."
    }
  ]) {
    factSheet {
      id
      name
      type
      description
    }
  }
}

To update the description field, use a Patch operation.

Update a Fact Sheet

Method	Path	Reference
PUT	`/factSheets/{id}`	Schema

In this section, we provide an example of updating the description of a Fact Sheet.

REST call:

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

Example request body:

{
  "name": "TestFactSheet",
  "description": "This is the updated demo fact sheet description.",
  "displayName": "TestFactSheet",
  "fullName": "TestFactSheet"
}

GraphQL mutation:

mutation {
  updateFactSheet(id: "{id}"
  patches: [
    {
      op: replace
      path: "/description"
      value: "This is the updated description of a demo fact sheet."
    }
  ]) {
    factSheet {
      id
      name
      type
      description
    }
  }
}

Unlike the REST endpoint, the GraphQL mutation allows you to update data in a more granular way. You don't need to pass fields that you don't want to modify. In this example, we only update the description.

Archive a Fact Sheet

Method	Path	Reference
DELETE	`/factSheets/{id}`	Schema

REST call:

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

Example request body:

{
  "comment": "This is a test archive."
}

GraphQL mutation:

mutation {
  updateFactSheet(id: "{id}", 
    comment: "This is a test archive.", 
    patches: [{op: add, path: "/status", value: "ARCHIVED"}]) {
      factSheet {
        id
        name
        type
        description
        status
      }
  }
}

Create a Relation For a Fact Sheet

Method	Path	Reference
POST	`/factSheets/{id}/relations`	Schema

REST call:

https://{SUBDOMAIN}.leanix.net/services/pathfinder/v1/factSheets/{id}/relations

Example request body:

{
  "displayNameToFS": "TestRelation",
  "typeFromFS": "relToPredecessor",
  "typeToFS": "relToSuccessor",
  "activeFrom": "2023-11-29",
  "activeUntil": "2024-11-29",
  "constrainingRelations": [],
  "idsOfConstrainingRelations": [],
  "status": "ACTIVE",
  "fromId": "{id}",
  "toId": "{targetId}"
}

GraphQL mutation:

mutation {
  updateFactSheet(id: "{id}", patches: [
    {
    op: add,
    path: "/relToSuccessor/new_{id}",
    value: "{\"factSheetId\":\"{targetId}\",\"activeFrom\":\"2023-11-29\",\"activeUntil\":\"2024-11-29\"}"
	}
  ]) {
    factSheet {
      id
      name
      type
    }
  }
}

Update a Fact Sheet Relation

Method	Path	Reference
PUT	`/factSheets/{id}/relations/{relationId}`	Schema

REST call:

https://{SUBDOMAIN}.leanix.net/services/pathfinder/v1/factSheets/{id}/relations/{relationId}

Example request body:

{
  "id": "{relationId}",
  "displayNameToFS": "TestApp",
  "typeFromFS": "Application",
  "typeToFS": "Application",
  "permittedReadACL": [],
  "activeFrom": "2023-11-29",
  "activeUntil": "2025-11-29",
  "constrainingRelations": [],
  "fields": [],
  "status": "ACTIVE",
  "fromId": "{id}",
  "toId": "{targetFactSheetId}",
  "naFields": [],
  "type": "relToSuccessor"
}

GraphQL mutation:

mutation updateRelation {
  updateFactSheet(id: "{id}", patches: [
    {
    op: replace,
    path: "/relToSuccessor/{relationId}",
    value: "{\"description\":\"This is a test description.\",\"factSheetId\":\"{targetFactSheetId}\",\"activeFrom\":\"2023-11-29\",\"activeUntil\":\"2026-11-29\"}"
}
  ]) {
    factSheet {
      id
      name
      type
      ... on Application {
        relToSuccessor {
          edges {
            node {
              id
              activeFrom
              activeUntil
              description
            	factSheet {
                fullName
              }
            }
          }
        }
      }
    }
  }
}

In the example request, we update a relation for a Fact Sheet of the Application type.

Delete a Fact Sheet Relation

Method	Path	Reference
DELETE	`/factSheets/{id}/relations/{relationId}`	Schema

REST call:

https://{SUBDOMAIN}.leanix.net/services/pathfinder/v1/factSheets/{id}/relations/{relationId}

GraphQL mutation:

mutation {
  updateFactSheet(id: "{id}", patches: [
    {
    op: remove,
    path: "/relToSuccessor/{relationId}",
    value: ""
}
  ]) {
    factSheet {
      id
      name
      type
      ... on Application {
        relToSuccessor {
          edges {
            node {
              id
            	factSheet {
                fullName
              }
            }
          }
        }
      }
    }
  }
}

In the example request, we delete a relation for a Fact Sheet of the Application type.