Upcoming GraphQL API Changes (January 15, 2025)

Overview

To improve our API's overall robustness and consistency, we'll apply changes to our GraphQL API validation rules, which will take effect on January 15, 2025 after a grace period.

What's Changing

Previously, our GraphQL API validation allowed certain malformed queries to pass through. These queries represent edge cases and do not reflect typical usage patterns. We've identified and addressed these inconsistencies to ensure stricter validation. We anticipate that this change will only impact a few customers who may have unintentionally leveraged these validation loopholes in their integrations.

Also, we're implementing stricter validation of the number of tokens allowed in a single GraphQL request. This measure is aimed at enhancing the overall stability and performance of the API.

We're providing a grace period until January 15, 2025 to allow ample time for testing and adjustments. After this date, stricter validation will be enforced, and any non-compliant queries will fail.

What You Need to Do

To prepare for the upcoming changes to the GraphQL API, do the following:

Review API responses: Review API responses to ensure that they don't contain warning messages. If a warning message is returned, review the details in the response and adjust your queries as necessary.
Review your GraphQL API usage: Carefully examine your interaction with our API, particularly if you’ve implemented custom integrations.
Test your integrations: Before the effective date, thoroughly test your integrations to identify any potential issues caused by the stricter validation.
Update your integrations (if necessary): If your integrations rely on the previously allowed malformed queries, you'll need to update them to comply with the new validation rules. Also, you should check your queries to ensure that they don't exceed the allowed token limit.

How to Validate Queries

To validate queries in your integrations, include the HTTP header x-graphql-enable-extensions in your requests and set its value to true. If a query is invalid, a warning message is returned in extensions in the response. Without this HTTP header, no warning message will be returned for invalid queries.

"x-graphql-enable-extensions": "true"

In the GraphiQL interface in your workspace, a warning message is automatically returned for invalid queries.

Example Warning Message

For invalid requests, a warning message is returned in the response, as shown in the following example. The warning message and relevant details are returned in extensions, which is a new element introduced in responses. Review the details provided in reasons and adjust your queries as necessary.

{
  "data": { ... },
  "extensions": {
    "warnings": [
      {
        "message": "Your request contains elements that will be considered invalid after January 15, 2025 due to stricter GraphQL API validation rules. Please review and update your request as necessary.",
        "reasons": [
          "Invalid syntax encountered. There are extra tokens in the text that have not been consumed. Offending token '}' at line 10 column 1"
        ]
      }
    ]
  }
}

Resources and Support

We'll be updating our API documentation to reflect the new validation rules. The updated documentation will be available before the grace period ends.

If you have any questions or require further assistance, please don't hesitate to contact SAP LeanIX Support. If you're an SAP customer, submit a request from the SAP for Me portal.

Upcoming Changes

This section provides an overview of upcoming changes to the GraphQL API and what you need to do to prepare for them.

👍
Recommendation
Our interactive GraphiQL interface provides a convenient way to test and validate your queries against the latest schema. Paste your query into the GraphiQL editor and check the query for syntax errors. Syntax errors are highlighted in red. If needed, modify the query to ensure that there are no syntax errors. Then, run the query to ensure that it doesn't result in a warning message.
To learn more about using GraphiQL, see GraphiQL Tool.

Stricter Validation of Unconsumed Tokens

One of the upcoming API changes addresses the issue of unconsumed tokens in the request body. Previously, our validation might have allowed requests containing extra tokens (for example, }) at the end of the payload to pass through. Under the new validation rules, such requests will be flagged as malformed and will fail validation.

What You Need to Do

Review the payloads of your GraphQL API requests for any extraneous characters following the intended data. To ensure successful calls after the grace period, you should modify your code or tools to construct requests that strictly adhere to the documented syntax, avoiding any extraneous characters after defined parameters.

Example Query and Warning Message

Under the new validation rules, the following example request would fail.

Example query with unconsumed tokens:

{
  allFactSheets(first: 10, factSheetType: Application) {
    totalCount
    edges {
      node {
        id
        name
        type
      }
    }
  }
}}

Example warning message:

    "warnings": [
      {
        "message": "Your request contains elements that will be considered invalid after January 15, 2025 due to stricter GraphQL API validation rules. Please review and update your request as necessary.",
        "reasons": [
          "Invalid syntax encountered. There are extra tokens in the text that have not been consumed. Offending token '}' at line 12 column 2"
        ]
      }
    ]
  }

Stricter Validation of Invalid Tokens

Another upcoming API change involves stricter validation to catch requests with invalid syntax and unexpected tokens. Under the new validation rules, malformed requests will be flagged as invalid and will fail validation.

What You Need to Do

Ensure that there are no incorrectly escaped characters within your request data.
Ensure that your development environment and tools are configured to use the correct character encoding.
Examine specific warning messages returned by our API to identify the location and nature of the syntax issue.

Example Query and Warning Message

Under the new validation rules, the following example request would fail.

Example query with invalid tokens:

{
  ��factSheet(id: "28fe4aa2-6e46-41a1-a131-72afb3acf256") {
  ����displayName
  ��������... on Application {
  ������relApplicationToUserGroup {
  ��������edges {
  ����������node {
  ������������id
  ������usageType
  ������factSheet {
  ��������������level
  ��������������id
  ��������������name
  ��������������displayName
  ������������}
  ����������}
  ��������}
  ������}
  ����}
  ��}
  }

Example warning message:

[
      {
        "message": "Your request contains elements that will be considered invalid after January 15, 2025 due to stricter GraphQL API validation rules. Please review and update your request as necessary.",
        "reasons": [
          "Invalid syntax with ANTLR error 'token recognition error at: '�'' at line 2 column 3"
        ]
      }
]

Stricter Validation of the GraphQL Parsing Token Limit

We're implementing stricter validation of the number of tokens allowed in a single GraphQL request. This change is introduced to enhance the overall stability and performance of our GraphQL API.

What the Limit Means

In GraphQL, a request is broken down into smaller units called tokens during the parsing process. These tokens represent elements like keywords, variable names, field names, and string values.

An excessively large number of tokens in a single request can strain our parsing capabilities and potentially lead to performance issues. The limitation on the number of tokens ensures optimal API performance and a smooth experience for all users.

How This Affects Your Integrations

This change only affects customers who construct exceptionally complex GraphQL queries with a very high token count.

What You Need to Do

Review your GraphQL queries: Analyze your current GraphQL queries to identify any queries that might fail because of the token limit.
Refactor complex queries (if necessary): If you find queries exceeding the limit, explore ways to simplify or refactor them. This could involve breaking down the query into smaller, more manageable requests or optimizing the query structure.

Example Error Message

Under the new validation rules, queries exceeding the token limit will fail, and the following error message will be returned.

{
  "errors": [
    {
      "message": "The request contains too many characters. To prevent Denial Of Service attacks, parsing has been cancelled."
    }
  ]
}

Stricter Data Type Validation

We’re implementing stricter data type validation in GraphQL queries to improve data integrity and query accuracy. This enhancement aims to ensure that the data types passed in GraphQL queries align with the expected types, thereby mitigating potential errors and enhancing the overall query performance.

Here are some examples of warning messages that will be returned for requests where the data types do not match the expected ones:

Variable has an invalid value: Expected a String input, but it was a 'Integer': Returned when an integer value is passed where a string is expected.
Variable has an invalid value: Expected a String input, but it was a 'Boolean': Returned when a boolean value is passed where a string is expected.
Variable 'patches' has an invalid value: Expected a String input, but it was a 'Double': Returned when a double value is passed where a string is expected.

What You Need to Do

Validate your queries to ensure that the data types of passed values correspond to the expected types.

Example Mutation and Warning Message

The following example illustrates a mutation where the data type of the passed value in the variable does not match the expected type. In the description field, an integer value is provided where a string is expected, resulting in a warning message returned for this query.

Example mutation with a variable:

mutation($patches: [Patch]!) {
  updateFactSheet(
    id: "ed37c4fe-7c86-45cd-97de-02cabf05bc4c",
    patches: $patches
  ) {
    factSheet {
      id
      name
      description
    }
  }
}

Variable with an incorrect data type passed in value:

{
  "patches": {
    "op": "replace",
    "path": "/description",
    "value": 12345
  }
}

Example warning message:

  "warnings": [
    {
      "message": "Your request contains elements that will be considered invalid after January 15, 2025 due to stricter GraphQL API validation rules. Please review and update your request as necessary.",
      "reasons": [
        "Variable 'patches' has an invalid value: Expected a String input, but it was a 'Integer'"
      ]
    }
  ]

Overview

What's Changing

What You Need to Do

How to Validate Queries

Example Warning Message

Resources and Support

Upcoming Changes

👍Recommendation

Stricter Validation of Unconsumed Tokens

What You Need to Do

Example Query and Warning Message

Stricter Validation of Invalid Tokens

What You Need to Do

Example Query and Warning Message

Stricter Validation of the GraphQL Parsing Token Limit

What the Limit Means

How This Affects Your Integrations

What You Need to Do

Example Error Message

Stricter Data Type Validation

What You Need to Do

Example Mutation and Warning Message

👍
Recommendation