REST API

NOTE: The REST API is currently in alpha version. This means we are likely to make breaking changes in the next release. We also plan to expand the API to make more analysis information available. Contact Empear, and we are happy to share our detailed plans and get your feedback.

You can get the following information from the API:

  • The access user
  • The rest api documentation url
  • Project lists
  • Import Project
  • Single project details
  • Analyses list of a project
  • Single analysis details
  • Files list from analysis in descending order based on order_by value
  • Components list from an analysis
  • Single components details from an analysis
  • Files list from component in descending order based on order_by value

The REST API documentation URL

You can browse the REST API functions here CodeScene RestAPI Functions. Before trying any functionality, use the Authorize button then fill in your username and password to authenticate.
The version in use is v1

Using CodeScene’s REST API

The REST API user

CodeScene lets you create a user intended to consume the REST API. Login as administrator then create a new user and assign RestApi role to it as illustrated in Fig. 36.
Any user with role Admin, Architect or RestApi can consume the REST API
If you are using LDAP, you need to assign the Admin, Architect or RestApi role. Follow the instructions from LDAP Roles Settings to assign a role to a LDAP user.
OAuth user accounts are not supported.
Configure a RestApi user

Fig. 36 Configure a RestApi user to consume the REST API.

To consume the REST API, you need to authenticate using http basic authentication.
The REST API follows the default project access, project access mode and collaborators described in Project Access Management

Project lists

curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v1/projects'

Import Project

curl -X GET --header 'Accept: application/json' -u username:password \
--data "@./project-config.json" 'http://localhost:3003/api/v1/projects/new'
  • Replace ./project-config.json with a valid a path to your project configuration, the format is the one exported by CodeScene

Single project details

curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v1/projects/{project-id}'
  • Replace {project-id} with a valid id taken from the project list results.

Analysis List of a project

curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v1/projects/{project-id}/analyses'
  • Replace {project-id} with a valid id taken from the project list results.

Single analysis details

Single analysis details using its id
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v1/projects/{project-id}/analyses/{analysis-id}'
  • Replace {project-id} with a valid id taken from the project list results.
  • Replace {analysis-id} with a valid id taken from the analysis list results.
Latest analysis details
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v1/projects/{project-id}/analyses/latest'
  • Replace {project-id} with a valid id taken from the project list results.

Files list from an analysis

File list in descending order based on order_by value for given analysis id
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v1/projects/{project-id}/analyses/{analysis-id}/files?page={page}&page_size={page_size}&order_by={order_by}'
  • Replace {project-id} with a valid id taken from the project list results.
  • Replace {analysis-id} with a valid id taken from the analysis list results.
  • Replace {page} with required page to return. If page parameter is omitted the default value is 1.
  • Replace {page_size} with the number of files to return for a page. If page_size parameter is omitted the default value is 100.
  • Replace {order_by} with one of the following values: “lines_of_code”, “change_frequency”, “number_of_defects”, “code_health” or “cost”. If order_by parameter is omitted the default value is “change_frequency”.
Files list in descending order based on order_by value for latest analysis
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v1/projects/{project-id}/analyses/latest/files?page={page}&page_size={page_size}&order_by={order_by}'
  • Replace {project-id} with a valid id taken from the project list results.
  • Replace {page} with required page to return. If page parameter is omitted the default value is 1.
  • Replace {page_size} with the number of files to return for a page. If page_size parameter is omitted the default value is 100.
  • Replace {order_by} with one of the following values: “lines_of_code”, “change_frequency”, “number_of_defects”, “code_health” or “cost”. If order_by parameter is omitted the default value is “change_frequency”.

Components list from an analysis

Components list using analysis id
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v1/projects/{project-id}/analyses/{analysis-id}/components'
  • Replace {project-id} with a valid id taken from the project list results.
  • Replace {analysis-id} with a valid id taken from the analysis list results.
Latest analysis components list
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v1/projects/{project-id}/analyses/latest/components'
  • Replace {project-id} with a valid id taken from the project list results.

Single components details from an analysis

Component details using analysis id
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v1/projects/{project-id}/analyses/{analysis-id}/components/{component-name}'
  • Replace {project-id} with a valid id taken from the project list results.
  • Replace {analysis-id} with a valid id taken from the analysis list results.
  • Replace {component-name} with a valid name taken from the components list results.
Latest analysis component detail
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v1/projects/{project-id}/analyses/latest/components/{component-name}'
  • Replace {project-id} with a valid id taken from the project list results.
  • Replace {component-name} with a valid name taken from the components list results.

Component file list from an analysis

Component file list in descending order based on order_by value for given analysis id
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v1/projects/{project-id}/analyses/{analysis-id}/components/{component-name}/files?page={page}&page_size={page_size}&order_by={order_by}'
  • Replace {project-id} with a valid id taken from the project list results.
  • Replace {analysis-id} with a valid id taken from the analysis list results.
  • Replace {component-name} with a valid id taken from the component list results.
  • Replace {page} with required page to return. If page parameter is omitted the default value is 1.
  • Replace {page_size} with the number of files to return for a page. If page_size parameter is omitted the default value is 100.
  • Replace {order_by} with one of the following values: “lines_of_code”, “change_frequency”, “number_of_defects”, “code_health” or “cost”. If order_by parameter is omitted the default value is “change_frequency”.
Component files list in descending order based on order_by value for latest analysis
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v1/projects/{project-id}/analyses/latest/components/{component-name}/files?page={page}&page_size={page_size}&order_by={order_by}'
  • Replace {project-id} with a valid id taken from the project list results.
  • Replace {component-name} with a valid id taken from the component list results.
  • Replace {page} with required page to return. If page parameter is omitted the default value is 1.
  • Replace {page_size} with the number of files to return for a page. If page_size parameter is omitted the default value is 100.
  • Replace {order_by} with one of the following values: “lines_of_code”, “change_frequency”, “number_of_defects”, “code_health” or “cost”. If order_by parameter is omitted the default value is “change_frequency”.

Examples: Use Cases and Scripts

We use CodeScene’s REST API ourselves, and in this section we’d like to share some of the scripts we use. These scripts are particularly useful on large codebases as a basis for custom reports.

These examples are based on the following strategy: * Invoke the REST API using curl. * Parse the reply with the jq tool. * Pipe the response to other shell functions when needed.

As such, everything below is built using existing command line tools.

Let’s start by defining a helper function for calling the REST API:

call_api(){ curl -sS -u api:secret http://localhost:3003/api/v1$1; }
export -f call_api

Using the call_api utility, we can now query the REST API for specific purposes as illustrated in the following paragraphs.

Project Statistics

List project names and ids:

call_api /projects | jq -r '.projects[] | [.name,.id] | @csv' | sort

Calculate the total lines of code in the 10 most changed files:

call_api /projects/1/analyses/latest/files | jq -r '.files | sort_by(.change_frequency)
 | .[0:10] | .[].lines_of_code' |  paste -sd+ - | bc

Maintenance and Housekeeping

List all local repository paths for all projects (a bit more complex since we call the API in a loop):

call_api /projects | jq -r '.projects[].id' | while read id;do call_api /projects/$id \
| jq -r '.repository_paths_on_disk[]'; done | sort -u

File-Level Analysis Information

List the top hotspot files by change frequency:

call_api /projects/1/analyses/latest/files\?order_by=change_frequency | jq -r '.files[]
 | [.change_frequency,.name] | @csv'

Get some metrics for the top 25 hotspot files of a project:

call_api /projects/1/analyses/latest/files\?order_by=change_frequency\&page_size=25 \
| jq -r '.files[] | [.change_frequency,.code_health.health_now,.number_of_defects,.lines_of_code,.name] | @csv'

Architecture-Level Analysis Information

List a project’s architectural components sort by name:

call_api /projects/1/analyses/latest/components | jq -r '.components | sort_by(.name)| .[] | [.name, .ref] | @csv'

Get some metrics for the architectural component by name in a project:

call_api /projects/1/analyses/latest/components/`read -p "Enter component name: " name && echo $name` \
    | jq -r '[.age,.change_frequency,.lines_of_code,.system_health.current_score,.name] | @csv'

Get some metrics for all architectural components order by name in a project :

call_api /projects/1/analyses/latest/components | jq -r '.components | sort_by(.name)| .[] | .name' \
   | xargs -I % bash -c "call_api /projects/1/analyses/latest/components/% | jq -r '[.age,.change_frequency,.lines_of_code,.system_health.current_score,.name] | @csv'"