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¶
Using CodeScene’s REST API¶
The REST API user¶
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¶
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.
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¶
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”.
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¶
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.
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¶
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.
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¶
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”.
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'"