Introduction

Code Inspector had previously a REST API to trigger new analyses. This API is discontinued now in favor of our GraphQL API. The GraphQL API is more rich and exposes almost all Code Inspector data to you.

Basic information

• API endpoint: https://api.code-inspector.com/graphql
• Your API access key is passed using the X-Access-Key header
• Your API secret key is passd using the X-Secret-Key header

How to use the API

You can use the GraphQL API in two ways:

1. While being logged on the website: when you are logged on the website
2. Using an API key: that let’s you use code inspector by other processes using your account. This is how to use code inspector with your ci job for example.
3. Using Json Web Token (JWT): that is what is used by the responsive UI.

Creating an API key

Go on your user profile and generate an API key. Keep both the access and secret keys.

Creating a JWT

To create a JWT, issue a request like this on the GraphQL endpoint

mutation{
  authentication(identifier: <IDENTIFIER>, password: <PASSWORD)
  {
    token
    error
  }
}

If the request is successful, you get an answer as follow (where token) is a valid JWT token.

{
  "data": {
    "authentication": {
      "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjEABBHM3NDI2MzMsImlhdCI6MTU2MzY1NjIzMywidXNlcklInd8gMn0.iW4Fu1pPeqwMj-VAzxseeJv3wgcTc_uarTMXD3k19PM",
      "error": null
    }
  }
}

If there is any error, the error field will contains useful error as to why authentication failed.

Once you have a JWT, you need to pass it in the header when querying the GraphQL endpoint. Pass the Authorization header the the value Bearer <YOUR-TOKEN>.

For example, if we take the example from before, we will add an Authorization header as is:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjEABBHM3NDI2MzMsImlhdCI6MTU2MzY1NjIzMywidXNlcklInd8gMn0.iW4Fu1pPeqwMj-VAzxseeJv3wgcTc_uarTMXD3k19PM

Testing the endpoint

If you want to try the GraphQL endpoint with your API credentials, you can use a curl request as follow.

curl -i -H 'Content-Type: application/json' -H "X-Access-Key: <YOUR-ACCESS-KEY>" -H "X-Secret-Key: <YOUR-SECRET-KEY>" -X POST -d '{"query": "query {projects(howmany: 10, skip:0){name}}"}' https://api.code-inspector.com/graphql

Web Playground

While logged, you can play with the API by navigating on the playground on code-inspector.com/graphql/playground. Make sure that you are authenticated on the website. Also, in order to use your cookie to send a request, make sure the following line is included in the playground configuration:

"request.credentials": "include"

Requests guidelines

Complex Queries

We are rejecting queries that are putting too much load on our backend. These queries are labelled as complex queries. If you submit a complex queries, a message error “Query too complex” will be sent back. Make sure that any code sending queries to the GraphQL API handles such cases.

In order to evaluate the query complexity, we require users to specify how many objects they are querying and from where they are querying. This is done using the query arguments skip and howmany.

For example:

• the request projects(howmany: 10, skip:0){name} prints the name of the 10 first projects accessible to the logged user.
• the request projects(howmany: 2, skip:5){name} skips the first five projects and prints the name of the two following projects.

Examples of requests

Get the name and repository URL of the first ten projects

{
  projects(howmany: 10, skip:0){
    name
    status
    repository{
      url
    }
  }
}

Get the status and start time of the last analysis of project with name “POK”

{
  project(name: "POK"){
    name
    lastAnalysis{
      status
      startTimestamp
    }
  }
}

Analysis Summary

The following query shows the number of duplicates lines and number of violation of severity 1 for the last analysis of project “POK”.

{
  project(name: "POK"){
    name
    lastAnalysis{
      status
      startTimestamp
  		summary{
        duplicated_lines
      	violationsSeverity1
      }
    }
  }
}

Violations

The following query shows the the first 10 violations of the latest analysis of project POK. For each violation, we get the line, the file and the description of the violation.

{
  project(name: "POK"){
    name
    lastAnalysis{
      status
      startTimestamp
  		violations(howmany: 10, skip: 0){
        line
        language
        filename
        description
      }
    }
  }
}

Duplicates

This query shows the first 10 duplicates of the latest analysis of project POK. For each duplicate, it shows the number of duplicated lines and each occurrence (filename of the occurrence and location)

{
  project(name: "POK"){
    name
    lastAnalysis{
      status
      startTimestamp
  		duplicates(howmany: 10, skip: 0){
        lineCount
        occurrences{
          filename
          line
        }
      }
    }
  }
}

GraphQL schema

The best way to get the entire schema is through the GraphQL playground. There is a link on the right of the playground that lets you see the schema.