GraphQL API

GraphQL API is a tool that allows you to retrieve exactly the data you need using more specific and flexible queries. One of the main benefits of GraphQL API is that you can get many different resources using a single request.

For cases when you want to run queries against the Crowdin GraphQL API, we recommend using the GraphQL Playground app, with the help of which you can build, test and debug queries from Crowdin Enterprise web UI even before writing any code in your application.

Authorization with GraphQL API

To work with GraphQL API in Crowdin Enterprise, use one of the following access tokens:

• Personal Access Token
• OAuth Access Token

Ensure to use the following header in your requests:

Authorization: Bearer <ACCESS_TOKEN>

The response in case authorization fails:

401 Unauthorized

{
  "error": {
    "message": "Unauthorized",
    "code": 401
  }
}

Root Endpoint

In contrast to the REST API, GraphQL API has only one endpoint that remains constant, not depending on the performed operations.

GraphQL endpoint:

https://{domain}.api.crowdin.com/api/graphql

Resource Limitations

The Crowdin GraphQL API has limitations to prevent excessive or abusive calls to Crowdin servers.

Node Limit

All GraphQL API calls must comply with the following requirements to pass schema validation:

• Users must supply a first or last argument on any connection.
• Values of first and last must be within 1-10,000.
• Individual calls can’t request more than 10,000 total nodes.

Nodes Calculation

In the following examples, you can check out how the nodes in a call are calculated.

• Simple query:

  query {
    viewer {
      projects(first: 50) {
        edges {
          node {
            name
  
            files(first: 10) {
              totalCount
              edges {
                node {
                  name
                  type
                }
              }
            }
          }
        }
      }
    }
  }
  

  Calculation:

  50         = 50 projects
  +
  50 x 10    = 500 files
  
             = 550 total nodes
  

• Complex query:

  query {
    viewer {
      projects(first: 50) {
        edges {
          node {
            files(first: 20) {
              edges {
                node {
                  strings(first: 10) {
                    edges {
                      node {
                        ... on PlainSourceString {
                          text
                        }
                        ... on ICUSourceString {
                          text
                        }
                        ... on PluralSourceString {
                          plurals {
                            one
                            other
                          }
                        }
                        ... on AssetSourceString {
                          text
                        }
                      }
                    }
                  }
                }
              }
            }
  
            translations(first: 20, languageId: "uk") {
              edges {
                node {
                  ... on PlainStringTranslation {
                    text
                  }
                  ... on ICUStringTranslation {
                    text
                  }
                  ... on PluralStringTranslation {
                    pluralForm
                    text
                  }
                  ... on AssetStringTranslation {
                    text
                  }
                }
              }
            }
          }
        }
      }
    }
  }
  

  Calculation:

  50           = 50 projects
  +
  50 x 20      = 1,000 files
  +
  50 x 20 x 10 = 10,000 strings
  +
  50 x 20      = 1,000 translations
  
               = 12,050 total nodes
  

Rate Limit

The GraphQL API limit is quite different compared to the rate limits set for REST API.

As mentioned above, you can get the same amount of data using only one GraphQL call and replacing the need to execute multiple REST calls. While a single complex GraphQL call could be equivalent to thousands of REST requests and wouldn’t exceed the REST API rate limit, its computation might be just as expensive for Crowdin servers.

The GraphQL API uses a normalized point scale to precisely depict the server cost of a query by calculating a call’s rate limit score. This score includes the first and last arguments on a parent connection and its children.

• The formula uses the first and last arguments on a parent connection and its children to pre-determine the possible load on Crowdin systems, such as MySQL and ElasticSearch.
• Each new connection has its own point value. Points are added to the call’s other points to form a final rate limit score.

The GraphQL API rate limit is set to 5,000 points per hour. Since the GraphQL API and REST API use different rate limits, 5,000 points per hour aren’t the same as 5,000 calls per hour.

Checking Rate Limit Status of a Call

To check the rate limit status when using GraphQL API, query the fields on the rateLimit object:

query {
  viewer {
    username
  }
  rateLimit {
    limit
    cost
    remaining
    resetAt
  }
}

• limit – returns the maximum number of points the user is allowed to consume in a 60-minute window.
• cost – returns the point cost for the current call that counts against the rate limit.
• remaining – returns the number of points remaining in the current rate limit window.
• resetAt – returns the time at which the current rate limit window resets in UTC epoch seconds.

Estimating Rate Limit Score before Call Execution

While querying the rateLimit object can give you a call’s score, it counts against the limit. To work around this situation, you can estimate the score of a call in advance. Using the following calculation, you can get approximately the same cost as returned by rateLimit { cost }.

1. First, the number of requests required to fulfill each unique connection in the call should be added up. Suppose each request will reach the first or last argument limits.
2. Next, you need to divide the number by 100 and round the result to obtain the final combined cost. This step normalizes large numbers.

Here’s an example query and score calculation:

query {
  viewer {
    username
    projects(first: 100) {
      edges {
        node {
          id
          files(first: 50) {
            edges {
              node {
                id
                strings(first: 60) {
                  edges {
                    node {
                      ... on PlainSourceString {
                        id
                        text
                      }
                      ... on ICUSourceString {
                        id
                        text
                      }
                      ... on PluralSourceString {
                        id
                        plurals {
                          one
                          other
                        }
                      }
                      ... on AssetSourceString {
                        id
                        text
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

• While returning 100 projects, the API has to connect to the user’s account once to get the list of projects. So, requests for projects = 1
• While returning 50 files, the API has to connect to each of the 100 projects to get the list of files. So, requests for files = 100
• While returning 60 strings, the API has to connect to each of the 5,000 potential total files to get the list of strings. So, requests for strings = 5,000
• Total = 5,101

Now, divide the total of 5,101 by 100 and round it. As a result, you get the final score of the query, which is 51.