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
  • Single project details
  • Analyses List of a project
  • Single analysis details
  • Hotspot list from an analysis, optionally you can you filter the output by numberofdefects, size, number of revisions, cost
  • Files list from analysis in descending order based on order_by value
  • Architecture hotspot lists and system health for an analysis
  • Architecture components list
  • Architecture component files list, optionally you can you filter the output by numberofdefects, size, number of revisions, cost

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. 35.
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. 35 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'

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.

Hotspot list from an analysis

You can filter the result by number_of_defects, lines_of_code and change_frequency, in any combination of them.
Hotspot 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}/hotspots'
  • 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.
Hotspot list using analysis id - only hotspots with change_frequency >= 70 and lines_of_code => 100
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v1/projects/{project-id}/analyses/latest/hotspots?change_frequency=70&lines_of_code=100'
  • Replace {project-id} with a valid id taken from the project list results.
  • Replace {analysis-id} with a valid id taken from the analyses list results.
Top 15% Hotspot list using analysis id based on number of defects
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v1/projects/{project-id}/analyses/{analysis-id}/hotspots/numberofdefectspercentage/top/15'
  • Replace {project-id} with a valid id taken from the project list results.
  • Replace {analysis-id} with a valid id taken from the analyses list results.
  • Replace 15 with whatever percentage you like.
Top 25% Hotspot list using analysis id based on change frequency
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v1/projects/{project-id}/analyses/{analysis-id}/hotspots/changefrequencypercentage/top/25'
  • 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 25 with whatever percentage you like.
Latest analysis hotspot list
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v1/projects/{project-id}/analyses/latest/hotspots'
  • Replace {project-id} with a valid id taken from the project list results.
Latest analysis hotspot list - only hotspots with number_of_defects >= 10 and lines_of_code => 100
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v1/projects/{project-id}/analyses/latest/hotspots?number_of_defects=10&lines_of_code=100'
  • Replace {project-id} with a valid id taken from the project list results.
Latest analysis, top 5% hotspot list based on number of defects
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v1/projects/{project-id}/analyses/latest/hotspots/numberofdefectspercentage/top/5'
  • Replace {project-id} with a valid id taken from the project list results.
  • Replace 5 with whatever percentage you like.
Latest analysis, top 10% hotspot list based on change frequency
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v1/projects/{project-id}/analyses/latest/hotspots/changefrequencypercentage/top/10'
  • Replace {project-id} with a valid id taken from the project list results.
  • Replace 10 with whatever percentage you like.

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”.

Architecture hotspot lists and system health for an analysis

Architecture hotspot 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}/architecture/hotspots'
  • 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 architecture hotspot list
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v1/projects/{project-id}/analyses/latest/architecture/hotspots'
  • Replace {project-id} with a valid id taken from the project list results.

Architecture components list from an analysis

Architecture 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}/architecture/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 architecture components list
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v1/projects/{project-id}/analyses/latest/architecture/components'
  • Replace {project-id} with a valid id taken from the project list results.

Architecture 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}/architecture/components/{component-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 {component-id} 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/architecture/components/{component-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 {component-id} 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 components:

call_api /projects/1/analyses/latest/architecture/hotspots | jq -r '.value | 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 by age (last modification date):

call_api /projects/1/analyses/latest/architecture/hotspots | jq -r '.value \
 | sort_by(.age)[] | [.age,.name] | @csv'

Get some metrics for the architectural components in a project:

call_api /projects/1/analyses/latest/architecture/hotspots \
| jq -r '.value | sort_by(.change_frequency)[] \
| [.age,.change_frequency,.lines_of_code,.system_health.current_score,.name] | @csv'