Learn what's changing in our GraphQL API and how to prepare for these changes to avoid any issues with your integrations.
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."
}
]
}