[BETA] Getting started with Scompler GraphQL API

Package_PRO

The Scompler GraphQL API provides a GraphQL API interface for integrating Scompler into your workflows, allowing seamless connection with other tools in your tech stack. GraphQL is a data query language based on a schema whose validity is defined by the specification.

Authenticating with Scompler GraphQL API
Communicating with GraphQL
Schema introspection
Exploring Scompler GraphQL Capabilities
Limits
Errors
Pagination

Authenticating with Scompler GraphQL API

Authentication to the Scompler GraphQL API can be performed using a personal access token. An API access token is a secure key that allows authorized users to connect to Scompler’s API and perform tasks based on their assigned permissions. To generate an API access token, a user must be a member of a user group with the Scompler API permission enabled.

Steps to generate a Scompler API Access Token:
1. Navigate to your Scompler project settings.
2. Go to the Scompler API tab.
3. Click on Generate API Token.
4. Save the token securely, as it will not be displayed again.

NOTE: The Token is only visible during the process of creation and cannot be copied later on for security reasons.

The token adopts the permissions of the user who generates it. To separate API system operations from regular user activity, we recommend creating a dedicated system user for generating and using API tokens. This makes logs clearer and reduces confusion about who performed certain actions.

Regular token rotation is part of Scompler’s compliance with ISO 27001 and TISAX security standards. Tokens are valid for 180 days and must be renewed before they expire.

Communicating with Scompler GraphQL API

All communication with the Scompler GraphQL API is conducted through a single root endpoint. For pro.scompler.com, this is:

https://public-api.pro.scompler.com/graphql

In the case of GraphQL, regardless of whether you are performing a query or a mutation, the HTTP verb “POST” should be used. An exception is the introspection query, which can be called with “GET”.

Below is the anatomy of a typical request sent using “curl”:

shell
curl -X POST https://public-api.pro.scompler.com/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"query":"query { languages(first:10) { nodes { id name } } }"}'

Below is the anatomy of a typical mutation called using “curl”:

shell
curl -X POST https://public-api.pro.scompler.com/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"query":"mutation { createLanguage(input: { params: { name: \"Polish\", slug: \"pl-PL\" } }) { data { id }"}'

Schema introspection

Using introspection, you can ask the schema to describe itself. This feature is often used by tools like GraphQL Code Generator to generate type-safe client code.

* Send a “schema” query to retrieve information about the schema
graphql
     query {
           __schema {
                types {
                      name
                      kind
                      description
                      fields {
                           name
                      }
                }
           }
     }

Send a “type” query to retrieve information about any of the types
graphql
     query {
           __type(name: "AccountGroup") {
           name
           kind
           description
                fields {
                name
           }
           }
     }

You can also send a “GET” request to retrieve the full schema information
shell
curl https://public-api.pro.scompler.com/graphql \
-H "X-Operation-Name: IntrospectionQuery" \
-H "Authorization: Bearer TOKEN"

If you receive a response with “message: Unauthorized” or “401 Unauthorized”, ensure you are using a valid token.

Exploring Scompler GraphQL API Capabilities

You can run queries on your real data directly in the browser using an IDE that includes documentation, syntax highlighting, and error validation. This IDE is an instance of GraphiQL. For pro.scompler.com, it will be available in the browser at:
https://public-api.pro.scompler.com
Before you can send requests from the IDE, you’ll need to specify a header with your personal access token in the “Headers” tab:

Limits

The Scompler GraphQL API includes limits to protect against excessive or abusive calls. These limits are applied at both the network level (rate limits) and the schema level (nodes limits).

To avoid exceeding node limits, test your queries before using them in a real application.

To avoid exceeding a rate limit, you should pause at least 1 second between mutative requests and avoid concurrent requests.

Nodes limits

1. Each request is evaluated based on parameters such as the number and type of fields, as well as the depth of nesting. If the calculated cost exceeds the allowed limit, the request is not executed, and an error is returned:

json
{
"errors": [
{
"message": "Syntax Error: Query Cost limit of 1000 exceeded, found 1055.5."
}
]
}

Current Cost limit is set to 1000.

2. Each paginated query is further evaluated based on the number of items requested through the `first` or `last` arguments. Additionally, the values of these arguments themselves are also assessed:

One of these arguments must be specified.
The provided value must be in the range of 1 to 100.

Individual calls cannot request more than 50,000 total nodes.
If the calculated cost exceeds the allowed limit, the request is not executed, and an error is returned:

json
{
"data": null,
"errors": [
{
"message": "Cannot request more than 1000 nodes in a single document. Please split your operation into multiple sub operations or reduce the amount of requested nodes.",
"locations": [
{
"line": 1,
"column": 1
}
]
}
]
}

3. There is a limit on the maximum depth of nesting within a single query. If this limit is exceeded, the query is not executed, and an error is returned:

json
{
"errors": [
{
"message": "Syntax Error: Query depth limit of 7 exceeded, found 12."
}
]
}

The maximum depth limit is set to 7.

4. There is a limit on the maximum number of aliases in a single query. An example of a query with aliases:

graphql
query {
a: language(id: 10000654) {
name
}
b: language(id: 10000655) {
name
}
}

If this limit is exceeded, the query is not executed, and an error is returned:

json
{
"errors": [
{
"message": "Syntax Error: Aliases limit of 7 exceeded, found 10."
}
]
}

The maximum number of aliases is set to 7.

5. There is a limit on the maximum number of directives in a single query. An example of a query with directives:

graphql
query ($name:Boolean!) {
languages(first:10) {
nodes {
id
name1: name @skip(if: $name)
name2: name @skip(if: $name)
}
}
}

If this limit is exceeded, the query is not executed, and an error is returned:

json
{
"errors": [
{
"message": "Syntax Error: Directives limit of 20 exceeded, found 22."
}
]
}

The maximum number of directives is 20.

6. There is a limit on the maximum number of tokens in a single query. Individual tokens are considered separate syntactic units within the query. If a query exceeds the allowed number of tokens, it is not executed, and an error is returned:

json
{
"errors": [
{
"message": "Syntax Error: Token limit of 1000 exceeded."
}
]
}

The maximum number of tokens is set to 1000.

Rate Limits

Each user (each unique personal access token) has a limit on the number of simultaneously executed queries and mutations within a given time interval.

If a user with a given token exceeds the set limits, they will be unable to perform new queries until the interval has passed.

If the limit is exceeded, an error will be returned:

json
{
"errors": [
{
"message": "Rate limit of \"Query.*\" exceeded for \"Bearer TOKEN\"",
"locations": [
{
"line": 2,
"column": 3
}
],
"path": [
"languages"
]
}
],
"data": {
"languages": null
}
}

Additionally, the response headers will include a “retry-after” header containing the time interval after which it makes sense to retry the request. You should not retry your requests until this interval has passed:

Retry-After: 300000ms

Currently, the limit is set to 500 queries and 150 mutations within a time interval of 5 minutes.

Errors

If any errors occur, the response code will, in most cases, remain “200”. In case of any errors during request execution, the response will include an additional “errors” field with a description of the issue:

graphql
query {
languages {
nodes {
id
name
}
}
}

json
{
"data": null,
"errors": [
{
"message": "Missing pagination argument for field 'languages'. Please provide either the 'first' or 'last' field argument.",
"locations": [
{
"line": 2,
"column": 3
}
]
}
]
}

The same error format is used for mutations as well:

graphql
mutation {
createLanguage(input: { params: { name: "Polish" } }) {
data {
id
}
}
}

json
{
"errors": [
{
"message": "Field \"LanguageCreateInput.slug\" of required type \"String!\" was not provided.",
"locations": [
{
"line": 2,
"column": 34
}
]
}
]
}

Pagination

The Scompler GraphQL API has limits on the number of items that can be requested in a single query. When using such queries, you must specify either the “first” or “last” argument. The values for these arguments must be in the range of “1” to “100”.

If the information you request has more items than specified by the “first” or “last” argument, the query will be split into pages of a defined size.

Page navigation is done using a cursor and the “after” or “before” arguments. You can get cursor information by querying “pageInfo” in a paginated query. For example:

graphql
query {
languages(first:50, after:null) {
nodes {
id
name
}
pageInfo {
startCursor
endCursor
hasNextPage
hasPreviousPage
}
}
}

To request the next page of data, pass the value from “pageInfo.endCursor” into the “after” argument. For example:

graphql
query {
languages(first:50, after:"MQ") {
nodes {
id
name
}
pageInfo {
startCursor
endCursor
hasNextPage
hasPreviousPage
}
}
}

You can continue using “pageInfo.endCursor” until “pageInfo.hasNextPage” is equal to “false”.

Similarly, backward navigation is done using the “last” and “before” arguments, along with the values “pageInfo.startCursor” and “pageInfo.hasPreviousPage”.