REST API¶
We are expanding the API with every release to make more analysis information available. Contact Codescene, and we are happy to share our detailed plans and get your feedback.
You can get the following information from the API:
Using CodeScene’s REST API¶
The REST API documentation URL¶
The REST API user¶
Project endpoints¶
Projects list¶
curl -X GET --header 'Accept: application/json' -u username:password \
'https://localhost:3003/api/v2/projects'
Import Project Configuration¶
curl -X POST --header 'Content-Type: application/json' -u username:password \
--data "@./project-config.json" 'http://localhost:3003/api/v2/projects/new'
Replace
./project-config.json
with a valid a path to your project configuration, the format is the one exported by CodeSceneMinimal example for a project where you specify the local path
./specifiy-path-project-config.json
{
"config": {
"repo-paths": [
"/path/to/my/project"
],
"analysis-destination": "/path/to/save/analisys"
}
}
Minimal example for a project where you specify the remote git repository urls
./specifiy-remotes-project-config.json
{
"config": {
"repo-paths": [
"https://my.company.com/mycompany/project1.git",
"https://my.company.com/mycompany/project2.git",
"https://my.company.com/mycompany/project3.git"
],
"local-path-for-remotes": "/path/to/save/repository/",
"analysis-destination": "/path/to/save/analisys"
}
}
Export Project Configuration¶
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/projects/{project-id}/export/configuration/json'
Replace
{project-id}
with a valid id taken from the project list results.
Update Project Configuration¶
curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
--data '{"config" : {"description" : "this a project description"}}' \
'http://localhost:3003/api/v2/projects/{project-id}'
Replace
{project-id}
with a valid id taken from the project list results.The body payload can contain one or multiple attributes from the list below
{
"config": {
"branch-name-exclusion-pattern": "string",
"global-code-health-custom-rules": "string",
"complexitytrendwarninglookbackinmonths": "int",
"delta-always-comment": "boolean",
"team-analysis-sliding-window-time": "1 month/3 months/6 months/1 year/2 years/full",
"whitelistcontent": "string",
"ticketidpattern": "string",
"modus-commit-message-pattern": "string",
"selectdistinctcommits": "int",
"delivery-performance-strategy": "by-pm-transitions/by-git-tags",
"pair-programming-pattern": "string",
"temporal_coupling_across_minrevs": "int"0,
"max_historic_age": "int",
"exclusionfilter": "string",
"code-health-alert-level": "int",
"use-parallel-code-health-strategy": "boolean",
"mine-git-in-parallel": "boolean",
"git-rename-limit": "int",
"delivery-performance-release-tag": "string",
"fail_on_update_repositories": "int",
"delta-recommend-review-level": "boolean",
"parallelgitmining": "int",
"temporal_coupling_archlevel_across_minrevs": "int",
"hotspots-sliding-window-time": "1 month/3 months/6 months/1 year/2 years/full",
"hotspots-defect-mining-pattern": "string",
"spottrendspan": "int",
"fail-on-update-repositories": "boolean",
"age-is-last-commit": "boolean",
"maxchangesetsize": "int",
"disable-code-health-custom-rules": "boolean",
"pair-programming-author-message-pattern": "string",
"temporal_coupling_across_maxchangesetsize": "int",
"complete-history-for-social": "boolean",
"lookup-copied-content": "boolean",
"name": "string",
"calculate-branch-statistics": "boolean",
"modus_commit_message_pattern": "string",
"present-x-ray-overloads-separately": "boolean",
"scan-all-code-in-project": "boolean",
"max_branch_risk_history_depth": "int",
"temporal-coupling-strategy": "by-ticket-id/by-time",
"ticket-id-uri-template": "string",
"project_owner": "string",
"minrevs": "int",
"update-repositories": "boolean",
"excludecontent": "string",
"rollingaveragedays": "int",
"auto-detect-text-files": "boolean",
"code_comment_enabled": "boolean",
"exdevcontribenabled": "int",
"limit_branch_prediciton_commits": "boolean",
"xrayallrevisions": "int",
"start-date": "string",
"max_history_depth": "int",
"branches-analysis-lookback-weeks": "int",
"analysis-start-date": "string",
"description": "string",
"combine-authors-field-and-commit-msg-to-deduce-pairs?": "boolean",
"pm-data-sliding-window-time": "1 month/3 months/6 months/1 year/2 years/full",
"minexdevcontribtime": "int",
"team-analysis-start-date": "string",
"code-ownership-source-file-names": "string"
"group-id": "int"
}
}
Single project details¶
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/projects/{project-id}'
Replace
{project-id}
with a valid id taken from the project list results.
Delete project¶
curl -X DELETE --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/projects/{project-id}'
Replace
{project-id}
with a valid id taken from the project list results.
Add git repository url’s (deprecated)¶
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
--data '{"urls":["https://mycompany.com/projects/p1.git", "https://mycompany.com/projects/p2.git"]}' \
'http://localhost:3003/api/v1/projects/{project-id}/repository/add'
Replace
{project-id}
with a valid id taken from the project list results.The body can contain one or multiple Git repository URLs. By default, an architectural component for each repository will be created. This behaviour can be changed by adding the boolean parameter “generate-architectural-component”. Here is an example of a payload:
'{"urls":["https://mycompany.com/projects/p1.git", "https://mycompany.com/projects/p2.git"], \
"generate-architectural-component":false }'
Add git repositories¶
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
--data '{"repositories":[{"url": "https://mycompany.com/projects/p1.git", "branch": "main"}, {"url": "https://mycompany.com/projects/p2.git", "branch": "1.0.x"}]}' \
'http://localhost:3003/api/v2/projects/{project-id}/repository'
Replace
{project-id}
with a valid id taken from the project list results.The body can contain one or multiple Git repositories with url and branch(is optional, if missing default repository branch will be used). By default, an architectural component for each repository will be created. This behaviour can be changed by adding the boolean parameter “generate-architectural-component”. Here is an example of a payload:
'{"repositories":[{"url": "https://mycompany.com/projects/p1.git", "branch": "main"}], \
"generate-architectural-component":false }'
Edit git repository branch¶
curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
--data '{"repositories":[{"url": "https://mycompany.com/projects/p1.git", "branch": "v.0.1"}]}' \
'http://localhost:3003/api/v2/projects/{project-id}/repository'
Replace
{project-id}
with a valid id taken from the project list results.the url must be already registered to the project
The body can contain one or multiple Git repositories with url and branch
Remove git repository url’s¶
curl -X DELETE --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
--data '{"urls":["https://mycompany.com/projects/p1.git", "https://mycompany.com/projects/p2.git"]}' \
'http://localhost:3003/api/v2/projects/{project-id}/repository/remove'
Replace
{project-id}
with a valid id taken from the project list results.the body can contain one or multiple git repository url’s
Update Project by importing development teams¶
curl -X POST --header 'Content-Type: text/csv' --header 'Accept: application/json' -u username:password \
--data "@./teams.csv" 'http://localhost:3003/api/v2/projects/{project-id}/teams/import'
Replace
{project-id}
with a valid id taken from the project list results.Replace
./teams.csv
with a valid a path to your teams configuration, the format is the one exported by CodeScene, first row of the file is the headerExample file
./teams.csv
author,team
max,backend
john,backend
sherri,ui
Get Project PR Integration with webhooks list¶
CodeScene support PR integration with following providers: github, bitbucket-server, gitlab, azure, github-app, bitbucket, gerrit
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/projects/{project_id}/pr-integration'
Replace
{project_id}
with a valid id taken from the project list results.
Update Project PR Integration¶
Each provider require a custom configuration to be set.
github example
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
-d '{ \
"github-token": "Specify a GitHub API token with repo and repo_hook:write permissions.", \
"github-host-url": "The external webhooks will call CodeScene using this Host URL. If left blank, the global Host URL is used. ", \
"github-api-url": "Specify the GitHub API URL. If left blank, a default API URL is constructed from the repository paths." \
}' 'http://localhost:3003/api/v2/projects/{project_id}/pr-integration/github'
bitbucket-server example
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
-d '{ \
"bitbucket-server-api-url": "Specify the Bitbucket API URL. If left blank, a default API URL is constructed from the repository paths.", \
"bitbucket-server-host-url": "The external webhooks will call CodeScene using this Host URL. If left blank, the global Host URL is used.", \
"bitbucket-server-token": "Specify a Bitbucket API token with Projects:read and Repositories:admin permissions.The token must be created by a user with the REPO_ADMIN permission." \
}' 'http://localhost:3003/api/v2/projects/{project_id}/pr-integration/bitbucket-server'
gitlab example
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
-d '{ \
"gitlab-api-url": "Specify the GitLab API URL. If left blank, a default API URL is constructed from the repository paths.", \
"gitlab-host-url": "The external webhooks will call CodeScene using this Host URL. If left blank, the global Host URL is used.", \
"gitlab-token": "Specify a GitLab API token with api permissions." \
}' 'http://localhost:3003/api/v2/projects/{project_id}/pr-integration/gitlab'
azure example
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
-d '{ \
"azure-api-url": "Specify the Azure API URL. If left blank, a default API URL is constructed from the repository paths.", \
"azure-host-url": "The external webhooks will call CodeScene using this Host URL. If left blank, the global Host URL is used.", \
"azure-token": "Specify an Azure API token with Code:Read & Write and Service Connections:Read, query, & manage permissions." \
}' 'http://localhost:3003/api/v2/projects/{project_id}/pr-integration/azure'
github-app example
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
-d '{ \
"github-app-app-id": "Specify the app id for the app you create on GitHub.", \
"github-app-private-ke": "The content of the .pem file you download by generating a private key for the app on GitHub.", \
"github-app-secret": "Specify the webhook secret for the app you create on GitHub.", \
"github-app-annotations": "Boolean, if true annotations will be added to CheckRun.", \
}' 'http://localhost:3003/api/v2/projects/{project_id}/pr-integration/github-app'
bitbucket example
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
-d '{ \
"bitbucket-api-url": "Specify the Bitbucket API URL. If left blank, a default API URL is constructed from the repository paths. ", \
"bitbucket-host-url": "The external webhooks will call CodeScene using this Host URL. If left blank, the global Host URL is used.", \
"bitbucket-token": "Specify a Bitbucket App Password with Pull requests:write and Webhooks:write permissions.", \
"bitbucket-username": "Specify the Bitbucket Username." \
}' 'http://localhost:3003/api/v2/projects/{project_id}/pr-integration/bitbucket'
gerrit example
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
-d '{ \
"gerrit-api-url": "Specify the Gerrit API URL. If left blank, a default API URL is constructed from the repository paths.", \
"gerrit-host-url": "The external webhooks will call CodeScene using this Host URL. If left blank, the global Host URL is used.", \
"gerrit-token": "Specify the Gerrit Http Password.", \
"gerrit-username": "Specify the Gerrit Username.", \
"gerrit-origin-url": "Specify the Gerrit Origin URL to use for fetching changes, if different from the configured repository origin URL. " \
}' 'http://localhost:3003/api/v2/projects/{project_id}/pr-integration/gerrit'
Disable Project PR Integration¶
curl -X DELETE --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/projects/{project_id}/pr-integration'
Replace
{project_id}
with a valid id taken from the project list results.
Get Project Badge Status¶
CodeScene support the following badges: code-health, missed-goals, system-mastery
curl -X GET --header 'Accept: application/json' -u username:password \
'https://localhost:3003/api/v2/projects/{project_id}/badges'
Replace
{project_id}
with a valid id taken from the project list results.
Update Project Badge Status¶
curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' \
-u username:password -d '{"code-health":true, "missed-goals": true ,"system-mastery": false}' \
'https://localhost:3003/api/v2/projects/{project_id}/badges'
Replace
{project_id}
with a valid id taken from the project list results.
Analyses endpoints¶
Analysis List of a project¶
curl -X GET --header 'Accept: application/json' -u username:password \
'https://localhost:3003/api/v2/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 \
'https://localhost:3003/api/v2/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 \
'https://localhost:3003/api/v2/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 \
'https://localhost:3003/api/v2/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 \
'https://localhost:3003/api/v2/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 \
'https://localhost:3003/api/v2/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 \
'https://localhost:3003/api/v2/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 \
'https://localhost:3003/api/v2/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 \
'https://localhost:3003/api/v2/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 \
'https://localhost:3003/api/v2/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 \
'https://localhost:3003/api/v2/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”.
Commit activity trend from an analysis¶
curl -X GET --header 'Accept: application/json' -u username:password \
'https://localhost:3003/api/v2/projects/{project-id}/analyses/{analysis-id}/commit-activity'
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 \
'https://localhost:3003/api/v2/projects/{project-id}/analyses/latest/commit-activity'
Replace
{project-id}
with a valid id taken from the project list results.
Skills inventory: programming language experience and distribution¶
Successful software maintenance requires the organization to maintain system mastery of the codebase. One aspect of that mastery is to make sure you have people who know all the implementation technologies and that there aren’t any bottlenecks (e.g. “we cannot finish that feature, because our only APL programmer is on a 3 months vacation”). CodeScene’s skills inventory analysis provides input to system mastery discussions and planning.
In general, CodeScene answers the following questions:
How many developers know language X?
Who are those developers, and what are their relative contribution experience in that technology?
The analysis info is available both for the whole codebase as well as for specific sub-systems and components. Use this information as input to discussions on:
Do we need to train more people in a specific programming language?
Do we have to hire people for a specific programming language?
Do we have enough C#/C++/Java/Python programmers in that critical sub-system where we plan lots of new features?
Before we look at the specific endpoints, lets explain the contribution fields that you will find in the responses:
In combination with CodeScene’s on- and off-boarding simulation module, you can also use this information to see the effects of rotating staff between different sub-systems or components and identify key personnel on a technical level.
There are two main REST endpoints:
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/projects/{project-id}/analyses/latest/experience/languages'
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/projects/{project-id}/analyses/latest/experience/languages/{language}'
Replace
{project-id}
with a valid id taken from the project list results.Replace
{language}
with the name of a programming language, e.g. JavaScript, Python, etc.
Both of these endpoints also exist on a component level. The response format is identical, only limited to programming languages and contribution statistics withing the given component:
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/projects/{project_id}/analyses/latest/components/{component}/experience/languages'
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/projects/{project_id}/analyses/latest/components/{component}/experience/languages/{language}'
Replace
{project-id}
with a valid id taken from the project list results.Replace
{language}
with the name of a programming language, e.g. JavaScript, Python, etc.Replace
{component-name}
with a valid id taken from the component list results.
Delta Analyses List of a project¶
curl -X GET --header 'Accept: application/json' -u username:password \
'https://localhost:3003/api/v2/projects/{project-id}/delta-analyses'
Replace
{project-id}
with a valid id taken from the project list results.
Single delta analysis details¶
curl -X GET --header 'Accept: application/json' -u username:password \
'https://localhost:3003/api/v2/projects/{project-id}/delta-analyses/{delta-analysis-id}'
Replace
{project-id}
with a valid id taken from the project list results.Replace
{delta-analysis-id}
with a valid id taken from the delta analysis list results.
Groups endpoints¶
Groups list¶
To call this endpoint you must be authenticated with an admin username.
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/groups'
Projects in group list¶
To call this endpoint you must be authenticated with an admin username.
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/groups/{groups-id}/projects'
Replace
{groups-id}
with a valid id taken from the groups list results.
Users and Roles endpoints¶
Users list¶
To call this endpoint you must be authenticated with an admin username.
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/users'
Create User¶
To call this endpoint you must be authenticated with an admin username.
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-u username:password -d '{ "username": "my_new_username", "password": "qwerty"}' \
'http://localhost:3003/api/v2/users/new'
the body must contain the username and password as json, the newly created user will have the default role “Full Read-Only Access”.
Get User by username¶
To call this endpoint you must be authenticated with an admin username.
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/users/{username}'
Replace
{username}
with a valid username taken from the users list results.
Roles list¶
To call this endpoint you must be authenticated with an admin username.
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/roles'
Authentication providers list¶
To call this endpoint you must be authenticated with an admin username.
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/authentication-providers'
Get authentication provider¶
To call this endpoint you must be authenticated with an admin username.
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/authentication-providers/{provider_id}'
Replace
{provider_id}
with a valid provider id taken from the authentication providers list results.
Update authentication provider¶
To call this endpoint you must be authenticated with an admin username.
Only authentication providers of type ldap and oauth2 can be updated.
Example of updating ldap authentication provider
curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
-d '{ "active?": true, \
"codescene_default_role": 1, \
"auth_provider_config": { \
"search_base": "(|(OU=people,OU=Internal,DC=medtronic,DC=com)(ou=serviceaccounts,ou=internal,dc=mycomapny,dc=com))" \
"connection_timeout": "5000", \
"response_timeout": "5000", \
"port": "636", \
"host": "ldap.mycompany.com", \
"ssl?": true, \
"bind_dn_format": "uid={username},OU=people,OU=Internal,DC=mycomapny,DC=com"} \
}' \
'http://localhost:3003/api/v2/authentication-providers/{provider_id}'
Replace
{provider_id}
with a valid provider id taken from the authentication providers list results.The body must contain the active? true/false, codescene_default_role the id must be a valid role id taken from the roles list results and auth_provider_config map with all the fields like in the example above, please adapt the values according to you setup.
Example of updating oauth2 authentication provider
curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
-d '{"active?": true, \
"codescene_default_role": 1, \
"auth_provider_config": { \
"teams_url": "http://my.oauth2.com/protocol/openid-connect/teaminfo", \
"teamname_field": "$.group[*]", \
"access_token_url": "http://my.oauth2.com/protocol/openid-connect/token", \
"scope": "email roles profile", \
"provider_name": "mycompany", \
"authorization_url": "http://my.oauth2.com/protocol/openid-connect/auth", \
"username_field": "$.email", \
"client_id": "app-codescene", \
"client_secret": "my-client-secret", \
"user_url": "http://my.oauth2.com/protocol/openid-connect/userinfo" \
}}' \
'http://localhost:3003/api/v2/authentication-providers/{provider_id}'
Replace
{provider_id}
with a valid provider id taken from the authentication providers list results.The body must contain the active? true/false, codescene_default_role the id must be a valid role id taken from the roles list results and auth_provider_config map with all the fields like in the example above, please adapt the values according to you setup.
Authentication provider role mapping list¶
To call this endpoint you must be authenticated with an admin username. If no query parameters are present the result represent the role mappings at global level. Use either group-id or project-id to get the role mappings at group or project level.
curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/authentication-providers/{provider_id}/role-mappings?group-id={group_id}&project-id={project_id}'
Replace
{provider_id}
with a valid provider id taken from the authentication propviders list results.Replace
{group_id}
with a valid id taken from the groups list results, the result represent the role mappings at the group level.Replace
{project_id}
with a valid id taken from the projects list results, the result represent the role mappings at the project level.
Add role mapping to authentication provider¶
To call this endpoint you must be authenticated with an admin username.
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-u username:password -d '{ "identifier": "my-identifier", "role_id": 8, "group_id": 1, "project_id: 2"}' \
'http://localhost:3003/api/v2/authentication-providers/{provider_id}/role-mappings'
replace
{provider_id}
with a valid provider id taken from the authentication providers list results.omit the
group_id
andproject_id
parameters to add a mapping at the global level.use the
group_id
orproject_id
parameters to add a mapping at group or project level.the body must contain the identifier(user or group name) and role_id as json, the role_id must be a valid role id taken from the roles list results.
Remove role mapping from authentication provider¶
To call this endpoint you must be authenticated with an admin username.
curl -X DELETE --header 'Content-Type: application/json' --header 'Accept: application/json' \
-u username:password -d '{ "identifier": "my-identifier", "group_id": 1, "project_id: 2"}' \
'http://localhost:3003/api/v2/authentication-providers/{provider_id}/role-mappings'
replace
{provider_id}
with a valid provider id taken from the authentication providers list results.omit the
group_id
andproject_id
parameters to remove the mapping from the global level.use the
group_id
orproject_id
parameters to remove the mapping from group or project level.
Teams and Developers endpoints¶
Developer Settings list¶
curl -X GET --header 'Accept: application/json' -u username:password \
'https://localhost:3003/api/v2/developer-settings'
Teams list¶
curl -X GET --header 'Accept: application/json' -u username:password \
'https://localhost:3003/api/v2/developer-settings/{developer_setting_id}/teams'
Replace
{developer_setting_id}
with a valid id taken from the developer settings list results.
Create team¶
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-u username:password -d '{ "team_name": "my-new-team"}' \
'https://localhost:3003/api/v2/developer-settings/{developer_setting_id}/teams/new'
Replace
{developer_setting_id}
with a valid id taken from the developer settings list results.
Update team¶
curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' \
-u username:password -d '{ "team_name": "my-updated-team"}' \
'https://localhost:3003/api/v2/developer-settings/{developer_setting_id}/teams/{team_id}'
Replace
{developer_setting_id}
with a valid id taken from the developer settings list results.Replace
{team_id}
with a valid id taken from the teams list results.
Delete team¶
curl -X DELETE --header 'Accept: application/json' -u username:password \
'https://localhost:3003/api/v2/developer-settings/{developer_setting_id}/teams/{team_id}'
Replace
{developer_setting_id}
with a valid id taken from the developer settings list results.Replace
{team_id}
with a valid id taken from the teams list results.
Developer list¶
curl -X GET --header 'Accept: application/json' -u username:password \
'https://localhost:3003/api/v2/developer-settings/{developer_setting_id}/developers'
Replace
{developer_setting_id}
with a valid id taken from the developer settings list results.
Update developer¶
curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' \
-u username:password -d '{ "team_id": 12, "former_contributor": true, "exclude_from_all_analyses": true}' \
'https://localhost:3003/api/v2/developer-settings/{developer_setting_id}/developers/{developer_id}'
Replace
{developer_setting_id}
with a valid id taken from the developer settings list results.Replace
{developer_id}
with a valid id taken from the developers list results.Set the team_id to a valid id taken from teams list if you need to assign the current developer to that team.
The only updateable attributes of a developer are the team_id, former_contributor and exclude_from_all_analyses
The payload can contain any of the attributes or only some of them.
Delete developer¶
curl -X DELETE --header 'Accept: application/json' -u username:password \
'https://localhost:3003/api/v2/developer-settings/{developer_setting_id}/developers/{developer_id}'
Replace
{developer_setting_id}
with a valid id taken from the developer settings list results.Replace
{developer_id}
with a valid id taken from the developers list results.
Remove Developer from Team¶
curl -X DELETE --header 'Accept: application/json' -u username:password \
'https://localhost:3003/api/v2/developer-settings/{developer_setting_id}/developers/{developer_id}/team'
Replace
{developer_setting_id}
with a valid id taken from the developer settings list results.Replace
{developer_id}
with a valid id taken from the developers list results.
KPI trends endpoints¶
The KPI trends endpoints lets you get the data behind the graphs and metrics found on CodeScenes 4-factors dashboards, as described in From Code to Delivery: the 4 factors model.
A full and current documentation of the endpoints can be found at the REST API documentation URL, see above for usage and authorization.
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/v2$1 ${@:2}; }
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 the current code health score + the number of defects 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.current_score,.number_of_defects,.lines_of_code,.name] | @csv'
Get the analysis schedule in cron format for all projects:
call_api /projects | jq -r '.projects[].id' | while read id;do call_api /projects/$id/export/configuration/json \
| jq -r .config.analysisplan; done
Code Health Analysis¶
List the 100 most worked on files together with their code health trend, and sort by relevance:
call_api /projects/1/analyses/latest/files\?order_by=change_frequency\&page_size=100 \
| jq -r '.files[] | [.change_frequency,.code_health.current_score,.code_health.month_score,.code_health.year_score,.name] | @csv'
Code Health Rules¶
The /metadata endpoint lets you access global rules and information. Here’s how you retrieve a list of all the code health rules that you can come across in a Virtual Code Review:
call_api /metadata/code-health-rules \
| jq -r '.code_health_rules[] | [.code_health_rule] | @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'"
Create New Project¶
CodeScene is using the following environment variables when creating a new project, for Tomcat deployment, you can also use JNDI Context properties
- CODESCENE_ANALYSIS_RESULTS_ROOT¶
“/path/to/analysis/”
- CODESCENE_CLONED_REPOSITORIES_ROOT¶
“/path/to/repositories/”
Example of create a new project using git repo URL and using environment variables
call_api /projects/new -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ "config": { "repo-paths": ["https://github.com/my-project/my-project-1.git"] } }'
This will create a project with name ‘my-project-1’
Example of create a new project using git repo URL without setting environment variables, you need to provide in the config the “local-path-for-remotes” and “analysis-destination”
call_api /projects/new -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ "config": { "repo-paths": ["https://github.com/my-project/my-project-2.git"], \
"local-path-for-remotes": "/path/to/repositories/", \
"analysis-destination": "/path/to/analysis/"} \
}'
This will create a project with name ‘my-project-2’
Example of create a new project using git repo URL (using environment variables)
call_api /projects/new -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ "config": { "repo-paths": ["https://github.com/my-project/my-project-3.git"]} \
}'
This will create a project with name ‘my-project-3’
Update Existing Project¶
Example of setting group id for existing project
call_api /projects/1 -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ "config": { "group-id": 2}}'
This will set the group with id 2 to the project with id 1