GraphQL API

What is GraphQL?

GraphQL is an API query language, originally created by Facebook as an alternative to REST. If you're new to GraphQL, the best place to start is the official documentation.

How do I make a query?

It depends on what kind of environment you are making the query from. Check out this list of GraphQL client libraries to see some tools already available in multiple languages, including C#/.NET, Go, Java, JavaScript, and Python. These client libraries can make writing queries easier and may provide built-in support for features like caching.

However, GraphQL is just a query language served over HTTP, so you can also make a request without using any GraphQL-specific libraries or packages. Here's an example using cURL (you'd need to replace the API key and test ID to try it yourself):

curl 'https://app.codesignal.com/graphql' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer MY_API_KEY' --data-binary '{"query":"{ companyTest(id: \"MY_TEST_ID\") { title } }"}'

This returns data that looks like this:

{"data":{"companyTest":{"title":"My Company Test"}}}

How can I test my queries during development?

Although you'll likely want to consume our API programmatically using a library in your language of choice, as you work on your integration, you may find it helpful to have a readily available UI for writing and running queries. For that, try out our GraphQL Playground, which is connected to our real API and provides a helpful interface that will make it easier for you to quickly spot and resolve syntax or schema issues in your queries.

To use the GraphQL Playground, you need to first generate an API key (see below) and then provide that in the HTTP Headers section in the bottom-left:

{ "Authorization": "Bearer YOUR_API_KEY" }

As long as you provide a valid API key, you can write and execute queries here and see the result immediately. If there are errors in your query syntax, red highlighting will appear on the left side of lines with errors, and you can hover over the query to learn more about what is wrong.

You can also explore the GraphQL schema and documentation live from the GraphQL Playground, as well as copy your query to a cURL command like the one from the previous section.

What kinds of queries can I make?

Take a look at our schema. All read-only queries can be found under RootQuery, and all mutations can be found under RootMutation.

Here's an example of a query that you could run to fetch the answers from a company test session:

query AnswerQuery {
  companyTestSession(id: "MY_TEST_SESSION_ID") {
    id
    result {
      taskResults {
        solution {
          id
          ... on CodingSolution {
            sources {
              source
              language
              path
            }
          }
          ... on FreeFormSolution {
            freeTextAnswer: answer
          }
          ... on QuizSolution {
            quizAnswer: answer
          }
        }
      }
    }
  }
}

In this case, we're using the graph-based nature of the API to make the following request: Look up a given company test session. For that session, return the ID and the result. For the result, return the result for each task, including the solution. For each solution, return the ID of the solution and more information depending on what kind of solution it is (using inline fragment syntax to query different fields based on type, and aliases to make sure the "answer" field does not conflict, since it has different types for free-text and quiz answers.

That might return something that looks like this:

{
  "data": {
    "companyTestSession": {
      "id": "MY_TEST_SESSION_ID",
      "result": {
        "taskResults": [
          {
            "solution": {
              "id": "MY_CODING_SOLUTION_ID",
              "sources": [
                {
                  "source": "console.log('hello world');",
                  "language": "js",
                  "path": "main.js"
                }
              ]
            },
          },
          {
            "solution": {
              "id": "MY_FREE_TEXT_SOLUTION_ID",
              "freeTextAnswer": "Hello, world!",
            },
          },
          {
            "solution": {
              "id": "MY_QUIZ_SOLUTION_ID",
              "quizAnswer": [
                "All of the above"
              ]
            },
          }
        ]
      }
    }
  }
}

How do I get an API key?

If you're not already using CodeSignal, start a conversation with us by requesting a demo.

If you're an existing customer, reach out to support@codesignal.com to learn more.

How do I make an authenticated request?

When making a GraphQL request, pass an "Authorization" header with a value of "Bearer YOUR_API_KEY" with the HTTP request. You can see a simple example of this in the cURL command above.

Some queries or mutations may require specific permissions to be assigned to your API key. If you receive Access Denied errors that you believe to be in error, please contact support.

What are rate limits and cost complexity, anyway?

Let's start with an analogy: Say you (the API consumer) are at home, ordering groceries (data) through a service like Instacart (the API).

A REST API is like a shopper who can only buy one item from the grocery store at a time. They can get any item in the store, but only one; if you want a second item, they have to make another full round-trip. For this kind of API, the main limit is a "rate limit." In other words, how frequently can you ask the shopper to go to the store?

On the other hand, GraphQL APIs are like shoppers who can buy a whole cart's worth of goods. Convenient! Like REST API shoppers, they may also have a limit on how frequently they can go to the store (a rate limit), but they can bring back a lot more groceries per trip. However, if you order too many things at once, they won't all fit in the shopping cart. The size of the shopping cart is the "maximum cost" allowed per trip.

What are CodeSignal's rate and cost limits?

Our rate limits vary based on the query or mutation; specific limits can be found in the schema documentation. Common values are 10 requests per second, or 5 requests per second.

Our maximum cost for a single query is 10000, and additionally we also don't allow queries with a depth greater than 10.

The cost of each resource can be found in the schema documentation, either as a scalar number or a multiplier based on the input. The total cost of a query will be determined by the cumulative cost of each queried resource.