API
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:
- While being logged on the website: when you are logged on the website
- 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.
- 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.