1. Introduction

coderadar server is a tool for continuous source code analysis. This document describes the REST API of coderadar. The REST API may for example be accessed by the following clients:

  • applications that provide a user interface for coderadar (like coderadar’s own user interface)

  • third-party applications or tools that want to integrate data provided by coderadar

This guide is aimed at developers of such applications.

1.1. Usage of HTTP Verbs

The following table describes how the coderadar API interprets the HTTP verbs.

Table 1. HTTP Verbs
HTTP Verb Usage

GET

GET is used to retrieve information.

POST

POST is used to create and update resources.

DELETE

DELETE is used to delete resources.

PUT

PUT is not used at this time.

PATCH

PATCH is not used at this time.

Usage of GET

If a GET request requires parameters, they can usually be provided as parameters encoded in the URL. However, in some cases parameters are too unwieldy to encode them in the URL. In these cases the parameters are expected as JSON string within the request body. Since some tools don’t allow GET requests with a body, coderadar accepts the POST method in these cases as well.

1.2. Error Handling

1.2.1. Successful Requests

Successful requests return a response with HTTP status 200 (OK) or 201 (CREATED) and contain a JSON structure in the response body if applicable.

1.2.2. Validation Errors

POST requests against the coderadar API usually expect a JSON structure in the request body. If the JSON structure contains values that are invalid, the API returns a response with HTTP status 400 (bad request) that contains an error JSON structure object that looks like this:

HTTP/1.1 400 Bad Request

1.2.3. General Errors

If some unexpected error occurs during the processing of a request, the API returns a response with HTTP status 500 (internal server error).

2. User Management

This section describes the REST endpoints for managing coderadar users.

2.1. Loading a User

Example Request

GET /api/users/2245 HTTP/1.1
Host: localhost:8080

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 72

{
  "id" : 2245,
  "username" : "username2",
  "platformAdmin" : false
}

2.2. Listing all Users

Example Request
GET /api/users HTTP/1.1
Host: localhost:8080
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 75

[ {
  "id" : 2252,
  "username" : "username",
  "platformAdmin" : false
} ]

2.3. Authentication

To access the functionality of coderadar you have to register a user. You need to define a username and a password. The password will be sent as plain text and hashed on server side for persisting.

2.3.1. Registering a User

Registration Data Structure
Path Type Description

username

String

The name of the user to be registered.

password

String

The password of the user as plaintext
Example Request
POST /api/user/registration HTTP/1.1
Content-Type: application/json
Content-Length: 57
Host: localhost:8080

{
  "username" : "username",
  "password" : "password1"
}
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 17

{
  "id" : 2247
}

2.3.2. Loading a User

Example Request
GET /api/users/2245 HTTP/1.1
Host: localhost:8080
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 72

{
  "id" : 2245,
  "username" : "username2",
  "platformAdmin" : false
}

2.3.3. Login

A user has to log in to use other endpoints of coderadar. If the log in is successful, user obtains two JSON Web Tokens https://jwt.io

  • an access token

  • a refresh token.

How to use the tokens is described in Authentication

Login Data Structure
Path Type Description

username

String

The name of the user to be logged in.

password

String

The password of the user as plaintext
Example Request
POST /api/user/auth HTTP/1.1
Content-Type: application/json
Content-Length: 57
Host: localhost:8080

{
  "username" : "username",
  "password" : "password1"
}
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 510

{
  "accessToken" : "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJjb2RlcmFkYXIiLCJleHAiOjE2NDgxMTEwMDksInR5cGUiOiJBQ0NFU1MiLCJpYXQiOjE2NDgxMTAxMDksInVzZXJJZCI6IjIxNzAiLCJ1c2VybmFtZSI6InVzZXJuYW1lIn0.vm6ItwCcbsw1CuotNFMhcCxj7cQxMNwhgWY0Ev6IJ2c",
  "refreshToken" : "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJjb2RlcmFkYXIiLCJleHAiOjE2NTMyOTQxMDksInR5cGUiOiJSRUZSRVNIIiwiaWF0IjoxNjQ4MTEwMTA5LCJ1c2VySWQiOiIyMTcwIiwidXNlcm5hbWUiOiJ1c2VybmFtZSJ9.DtmN4U3CNTsKRhhuL7lH8zm7WoXBIE2RFH974-7Ktc4",
  "userId" : 2170,
  "platformAdmin" : false
}

2.3.4. Token Refresh

To get a new access token after the current token has been expired you have to use the refresh token you got after successful login

Login Data Structure
Path Type Description

accessToken

String

The expired access token

refreshToken

String

The valid refresh token
Example Request
POST /api/user/refresh HTTP/1.1
Content-Type: application/json
Content-Length: 449
Host: localhost:8080

{
  "accessToken" : "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJjb2RlcmFkYXIiLCJleHAiOjE2NDgxMDkyNzMsInR5cGUiOiJBQ0NFU1MiLCJpYXQiOjE2NDgxMDgzNzMsInVzZXJJZCI6MSwidXNlcm5hbWUiOiJyYWRhciJ9.1HPhK_idyfQ948_JI3OXggIol6PiJHWk-rQCiByG-JY",
  "refreshToken" : "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJjb2RlcmFkYXIiLCJleHAiOjE2NTMyOTQxMTMsInR5cGUiOiJSRUZSRVNIIiwiaWF0IjoxNjQ4MTEwMTEzLCJ1c2VySWQiOiIyMjU0IiwidXNlcm5hbWUiOiJyYWRhciJ9.Ynj-CyvY_0bw_j3N3SKqjuHv_M_CZpalsB5we4z8Gyo"
}
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 222

{
  "token" : "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJjb2RlcmFkYXIiLCJleHAiOjE2NDgxMTEwMTMsInR5cGUiOiJBQ0NFU1MiLCJpYXQiOjE2NDgxMTAxMTMsInVzZXJJZCI6IjIyNTQiLCJ1c2VybmFtZSI6InJhZGFyIn0.XvT5IJIYbRJE17JyDAuav10RZFUt8JTkMx64WqDBFj8"
}

2.3.5. Password Change

To change the password user has to be authenticated by the access token and has to send a new password and thе refresh token to the server. The user will be found by the refresh token and his refresh tokens will be revoked so the user has to log in with the username and password again after the current access token is expired.

Data Structure
Path Type Description

refreshToken

String

the current refresh token of the user

newPassword

String

The password of the user as plaintext
Example Request
POST /api/user/password/change HTTP/1.1
Content-Type: application/json
Content-Length: 268
Host: localhost:8080

{
  "refreshToken" : "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJjb2RlcmFkYXIiLCJleHAiOjE2NTMyOTQxMDgsInR5cGUiOiJSRUZSRVNIIiwiaWF0IjoxNjQ4MTEwMTA4LCJ1c2VySWQiOiIyMTY2IiwidXNlcm5hbWUiOiJ1c2VybmFtZSJ9.AsDKare4weF4wPF3L64QctLFhVxPkcUlr9Aoq1ewzTE",
  "newPassword" : "newPassword1"
}
Example Response
HTTP/1.1 200 OK

2.3.6. Authentication

After a user registered, he or she can start working with coderadar. The first step is login. To log in in coderadar use the Login endpoint. The user must use the username and the password specified at registration. If the login was successful user gets two JSON Web Tokens (see https://jwt.io):

  • an access token and

  • a refresh token.

After that the user has to use the access token for authentication with each request to a protected route or resource. The tokens are signed by the server so the server can validate the signature of the token to grant the access to resources. The access token is a Base64 encoded String, that must be added to Authorization HTTP header like this:

Authorization:eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJjb2RlcmFkYXIiLCJleHAiOjE0ODQ1MTUzOTUsInR5cGUiOiJSRUZSRVNIIiwiaWF0IjoxNDg0NTE1NDU1LCJ1c2VySWQiOiIxIiwidXNlcm5hbWUiOiJyYWRhciJ9.zfkyc5jkPiAUEt7nU25SJxKprcPiXaiq0Q6bCJ_RrQo

The access token is short-lived and by default expires after 15 minutes. When the access token expires, the user has to require a new access token. It can be done with the refresh token user got as response after login. The refresh token must be sent with a request to the Token Refresh endpoint. The refresh token is long-lived and by default expires after 60 days. When the refresh token expired or was revoked for example after a password change, a user has to login again to get a new refresh token.

A typical work flow looks like this:

  1. Client logs in with username and password and gets two tokens

  2. Client requires resources using the access token in each request

  3. After 15 minutes client gets a 401-Response

  4. Clients tries to get a new access token using refresh token

  5. Clients gets a new access token and can request further resources

  6. If the client can’t get a new access token using the refresh token, client has to login again with username and password.

See more: https://auth0.com/docs/tokens/refresh-token and https://auth0.com/blog/refresh-tokens-what-are-they-and-when-to-use-them/

2.4. User Permissions

Users can be assigned to projects with a specific role.

2.4.1. Set user role in a project

Path Type Description

role

String

The role the user should have for the given project. Can be either ADMIN or MEMBER
Example Request
POST /api/projects/2164/users/2165 HTTP/1.1
Content-Type: application/json
Content-Length: 22
Host: localhost:8080

{
  "role" : "ADMIN"
}
Example Response
HTTP/1.1 200 OK

2.4.2. Remove user role from a project

Example Request
DELETE /api/projects/2156/users/2157 HTTP/1.1
Host: localhost:8080
Example Response
HTTP/1.1 200 OK

2.4.3. List all projects for a user

Example Request
GET /api/users/2251/projects HTTP/1.1
Host: localhost:8080
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 264

[ {
  "project" : {
    "id" : 2250,
    "name" : "project",
    "vcsUsername" : "testUser",
    "vcsPassword" : null,
    "vcsUrl" : "https://valid.url",
    "startDate" : "2022-03-24T08:21:52.742+0000",
    "defaultBranch" : null
  },
  "roles" : [ "ADMIN" ]
} ]

2.4.4. List all users for a project

Example Request
GET /api/projects/2142/users/ HTTP/1.1
Host: localhost:8080
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 75

[ {
  "id" : 2143,
  "username" : "username",
  "platformAdmin" : false
} ]

2.4.5. Setting user platform permissions

Example Request
POST /api/users/2159/admin?isAdmin=true HTTP/1.1
Content-Type: application/json
Host: localhost:8080

isAdmin=true
Example Response
HTTP/1.1 200 OK

2.4.6. Deleting a user

Example Request
DELETE /api/users/2147 HTTP/1.1
Host: localhost:8080
Example Response
HTTP/1.1 200 OK

Note: Deleting a user will also delete all projects created by them.

3. Configuring a Project

This section describes the resources you can interact with to configure a project to be analyzed by coderadar. To run an analysis on a project, you have to at least follow these steps:

  1. Create a Project so that coderadar knows where to get the code base. Once this step is done, coderadar will clone the repository and create some metadata on the commits and code base. Depending on the size of the project, it may take a while to complete.

  2. Define File Patterns to tell coderadar which files should be analyzed. If this step is omitted, an analysis will provide no results.

  3. Add at least one analyzer to your project. Each added analyzer will run over the files specified in the previous step and provide some code metrics.

  4. Start an Analyzing Job for your project. coderadar will start to analyze all files in the commits between startDate and endDate using the analyzers you have configured. Depending on the size of the code base and the number of configured analyzers, this may take some time to finish.

3.1. Project

A project defines some metadata about the project you want coderadar to analyze. With a project resource and its sub-resources you provide coderadar with the information it needs to analyze the source code.

3.1.1. Structure

Path Type Description

name

String

The name of the project to be analyzed.

vcsUrl

String

The URL to the version control repository where the project’s source files are kept.

vcsUsername

String

The user name used to access the version control system of your project. Needs read access only. Don’t provide this field if anonymous access is possible.

vcsPassword

String

The password of the version control system user. This password has to be stored in plain text for coderadar to be usable, so make sure to provide a user with only reading permissions. Don’t provide this field if anonymous access is possible.

vcsOnline

Boolean

Set to false if you want no interaction with a remote repository for this project. True by default.

defaultBranch

String

The default branch for the project.

startDate

Date

The start date of the range of commits which should be analyzed by coderadar. Leave empty to start at the first commit.

3.1.2. Creating a Project

Example Request
POST /api/projects HTTP/1.1
Content-Type: application/json
Content-Length: 270
Host: localhost:8080

{
  "name" : "project",
  "vcsUsername" : "username",
  "vcsPassword" : "password",
  "vcsUrl" : "file:/home/runner/work/coderadar/coderadar/coderadar-test/build/resources/test/test-repository",
  "vcsOnline" : false,
  "startDate" : null,
  "defaultBranch" : "master"
}
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 16

{
  "id" : 461
}

3.1.3. Listing Projects

Example Request
GET /api/projects HTTP/1.1
Host: localhost:8080
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 406

[ {
  "id" : 495,
  "name" : "project",
  "vcsUsername" : "testUser",
  "vcsPassword" : null,
  "vcsUrl" : "https://valid.url",
  "startDate" : "2022-03-24T08:21:26.982+0000",
  "defaultBranch" : null
}, {
  "id" : 496,
  "name" : "project",
  "vcsUsername" : "testUser",
  "vcsPassword" : null,
  "vcsUrl" : "https://valid.url",
  "startDate" : "2022-03-24T08:21:26.982+0000",
  "defaultBranch" : null
} ]

3.1.4. Updating a Project

Example Request
POST /api/projects/497 HTTP/1.1
Content-Type: application/json
Content-Length: 206
Host: localhost:8080

{
  "name" : "new-project-name",
  "vcsUsername" : "username",
  "vcsPassword" : "password",
  "vcsUrl" : "http://valid.url",
  "vcsOnline" : true,
  "startDate" : 1648110087006,
  "defaultBranch" : "dev"
}
Example Response
HTTP/1.1 200 OK

3.1.5. Get a Project

Example Request
GET /api/projects/494 HTTP/1.1
Host: localhost:8080
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 200

{
  "id" : 494,
  "name" : "project",
  "vcsUsername" : "testUser",
  "vcsPassword" : null,
  "vcsUrl" : "https://valid.url",
  "startDate" : "2022-03-24T08:21:26.957+0000",
  "defaultBranch" : null
}

3.1.6. Deleting a Project

Example Request
DELETE /api/projects/0 HTTP/1.1
Host: localhost:8080
Example Response
HTTP/1.1 200 OK

3.2. Modules

Source code is usually arranged within multiple modules that each contains a set of source files. Using the following REST endpoints, you can provide coderadar with information about the modules within your codebase. Each module simply is a path into the VCS codebase. All files that are within that path are considered to be part of the module.

Please note that the operations to create, update and delete modules may take some time to be finished since all files in all commits have to be updated during these operations.

3.2.1. Structure

Path Type Description

path

String

The path of this module starting at the VCS root. All files below that path are considered to be part of the module.

3.2.2. Creating a Module

Example Request
POST /api/projects/14/modules HTTP/1.1
Content-Type: application/json
Content-Length: 28
Host: localhost:8080

{
  "path" : "module-path"
}
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 15

{
  "id" : 15
}

3.2.3. Get a Module of a Project

Example Request
GET /api/projects/1/modules/2 HTTP/1.1
Host: localhost:8080
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 40

{
  "id" : 2,
  "path" : "test-module"
}

3.2.4. Listing all Modules of a Project

Example Request
GET /api/projects/3/modules HTTP/1.1
Host: localhost:8080
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 184

[ {
  "id" : 6,
  "path" : "test-module2"
}, {
  "id" : 7,
  "path" : "test-module/src/asd"
}, {
  "id" : 5,
  "path" : "test-module/src"
}, {
  "id" : 4,
  "path" : "test-module/"
} ]

3.2.5. Deleting a Module

Example Request
DELETE /api/projects/8/modules/9 HTTP/1.1
Host: localhost:8080
Example Response
HTTP/1.1 200 OK

3.3. Branches

3.3.1. Listing Branches

Example Request
GET /api/projects/184/branches HTTP/1.1
Host: localhost:8080
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 260

[ {
  "name" : "master",
  "commitHash" : -1587519487701415837,
  "isTag" : false
}, {
  "name" : "testBranch1",
  "commitHash" : -3231566689913255125,
  "isTag" : false
}, {
  "name" : "testBranch2",
  "commitHash" : -226973388931823875,
  "isTag" : false
} ]

3.4. File Patterns

A File Pattern describes a set of files within a Project’s code base. Each project can have several file patterns defined. File Patterns may either define a pattern for files to be INCLUDED or files to be EXCLUDED.

If a project has no File Patterns defined, the analysis won’t start.

3.4.1. Structure

Path Type Description

pattern

String

The pattern string of this FilePattern.

inclusionType

String

Whether the pattern is included or excluded.

3.4.2. Listing a Project’s File Patterns

Example Request
GET /api/projects/221/filePatterns HTTP/1.1
Host: localhost:8080
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 153

[ {
  "id" : 220,
  "pattern" : "**/*.xml",
  "inclusionType" : "EXCLUDE"
}, {
  "id" : 219,
  "pattern" : "**/*.java",
  "inclusionType" : "INCLUDE"
} ]

3.4.3. Adding a File Pattern to a Project

Example Request
POST /api/projects/222/filePatterns HTTP/1.1
Content-Type: application/json
Content-Length: 60
Host: localhost:8080

{
  "pattern" : "**/*.java",
  "inclusionType" : "INCLUDE"
}
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 16

{
  "id" : 223
}

3.4.4. Removing a File Pattern from a Project

Example Request
DELETE /api/projects/217/filePatterns/218 HTTP/1.1
Host: localhost:8080
Example Response
HTTP/1.1 200 OK

3.4.5. Get a specific File Pattern from a Project

Example Request
GET /api/projects/224/filePatterns/225 HTTP/1.1
Host: localhost:8080
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 74

{
  "id" : 225,
  "pattern" : "**/*.java",
  "inclusionType" : "INCLUDE"
}

3.4.6. Update a File Pattern for a Project

Example Request
POST /api/projects/222/filePatterns HTTP/1.1
Content-Type: application/json
Content-Length: 60
Host: localhost:8080

{
  "pattern" : "**/*.java",
  "inclusionType" : "INCLUDE"
}
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 16

{
  "id" : 223
}

3.5. Analyzer Configuration

Coderadar has a plugin system for source code analyzers so you can implement your own analyzers that produce the metrics you need (or you can use the analyzer plugins that are shipped with coderadar). For each project, you can configure each analyzer plugin via the AnalyzerConfiguration resource.

3.5.1. Structure

Path Type Description

analyzerName

String

Name of the analyzer plugin to which the AnalyzerConfiguration is applied. This should always be the fully qualified class name of the class that implements the plugin interface.

enabled

Boolean

Set to TRUE if you want the analyzer plugin to be enabled and to FALSE if not. You have to specify each analyzer plugin you want to have enabled. If a project does not have a configuration for a certain plugin, that plugin is NOT enabled by default.

3.5.2. Adding an Analyzer Configuration

Example Request
POST /api/projects/15/analyzers HTTP/1.1
Content-Type: application/json
Content-Length: 129
Host: localhost:8080

{
  "analyzerName" : "io.reflectoring.coderadar.analyzer.checkstyle.CheckstyleSourceCodeFileAnalyzerPlugin",
  "enabled" : true
}
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 15

{
  "id" : 16
}

3.5.3. Deleting an Analyzer Configuration

Example Request
DELETE /api/projects/12/analyzers/13 HTTP/1.1
Host: localhost:8080
Example Response
HTTP/1.1 200 OK

3.5.4. Updating an Analyzer Configuration

Example Request
GET /api/projects/0/analyzers/2 HTTP/1.1
Host: localhost:8080
Example Response
HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 67

{
  "errorMessage" : "AnalyzerConfiguration with id 2 not found."
}

3.5.5. Listing a Project’s Analyzer Configurations

Example Request
GET /api/projects/7/analyzers HTTP/1.1
Host: localhost:8080
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 138

[ {
  "id" : 8,
  "analyzerName" : "analyzer",
  "enabled" : true
}, {
  "id" : 9,
  "analyzerName" : "analyzer2",
  "enabled" : false
} ]

3.5.6. Loading a single Analyzer Configuration

Example Request
GET /api/projects/10/analyzers/11 HTTP/1.1
Host: localhost:8080
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 66

{
  "id" : 11,
  "analyzerName" : "analyzer",
  "enabled" : true
}

3.6. Analyzing

An analysis can be started for a project in coderadar. By default a Project’s codebase is not analyzed. To analyze the codebase an analysis has to be triggered.

3.6.1. Starting an Analysis

Example Request

The request body consists of a list of branch names and can be empty. In that case all branches are analyzed.

POST /api/projects/210/analyze HTTP/1.1
Content-Type: application/json
Host: localhost:8080
Example Response
HTTP/1.1 200 OK

3.6.2. Retrieving an Analysis status

Example Request
GET /api/projects/210/analyzingStatus HTTP/1.1
Host: localhost:8080
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 22

{
  "status" : false
}

3.6.3. Resetting an Analysis/Deleting Analysis results

Example Request
POST /api/projects/33/analyze/reset HTTP/1.1
Host: localhost:8080
Example Response
HTTP/1.1 200 OK

4. Querying Global Data

This section describes the resources that are not attached to a project and are thus available server-wide.

4.1. Analyzer

coderadar can be configured to use Analyzer plugins that analyze source code to create certain metrics.

4.1.1. Listing available Analyzers

Example Request
GET /api/analyzers HTTP/1.1
Host: localhost:8080
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 150

[ "io.reflectoring.coderadar.analyzer.checkstyle.CheckstyleSourceCodeFileAnalyzerPlugin", "io.reflectoring.coderadar.analyzer.loc.LocAnalyzerPlugin" ]

5. Querying Project Data

This section describes the resources that are attached to a project and are only available in the context of a project.

5.1. Metric

The Metric resource describes a metric that an analyzer configured in your project provides.

5.1.1. Listing available Metrics

You can list all metrics that have been measured for your project by calling the request below.

Metric values will become available as soon as an analysis starts for your project. At that moment, analysis of each commit in the date range starts The date range is set in the project settings. The project will only be regarded in this date range. Depending on how many commits that are and how many analyzers are configured, analysis will take a while.
Example Request
GET /api/projects/1959/metrics HTTP/1.1
Content-Type: application/json
Host: localhost:8080
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 113

[ "coderadar:size:cloc:java", "coderadar:size:loc:java", "coderadar:size:sloc:java", "coderadar:size:eloc:java" ]

5.2. Commit

The Commit resource contains some metadata about a commit to your project’s version control system. Commits will become available as soon as you have created a project and provided valid VCS credentials (see Creating a Project). Depending of the number of commits you have in your project, it may take a while until all commits are available.

5.2.1. Structure

Path Type Description

[]

Array

Array of all the commits in this project.

[].hash

String

The name/hash of the commit.

[].author

String

The author of the commit

[].authorEmail

String

The email of the author

[].comment

String

The comment of this commit

[].timestamp

Number

The timestamp of this commit

[].analyzed

Boolean

Whether this commit is already analyzed or not.

5.2.2. Listing a Project’s Commits

Example Request
GET /api/projects/2107/commits?branchName=master HTTP/1.1
Content-Type: application/json
Host: localhost:8080
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2907

[ {
  "hash" : "e9f7ff6fdd8c0863",
  "timestamp" : 1584013941000,
  "analyzed" : false,
  "author" : "Krause",
  "authorEmail" : "Kilian.Krause@adesso.de",
  "comment" : "modify testModule1/NewRandomFile.java"
}, {
  "hash" : "d3272b3793bc4b2b",
  "timestamp" : 1565615004000,
  "analyzed" : false,
  "author" : "maximAtanasov",
  "authorEmail" : "Maksim.Atanasov@adesso.de",
  "comment" : "testCommit"
}, {
  "hash" : "251dc2fde2db8d9a",
  "timestamp" : 1565598255000,
  "analyzed" : false,
  "author" : "maximAtanasov",
  "authorEmail" : "Maksim.Atanasov@adesso.de",
  "comment" : "modify GetMetricForCommitCommand.java"
}, {
  "hash" : "b7be4fc8d394e296",
  "timestamp" : 1565594249000,
  "analyzed" : false,
  "author" : "maximAtanasov",
  "authorEmail" : "Maksim.Atanasov@adesso.de",
  "comment" : "remove FindingRename.java"
}, {
  "hash" : "53e2f71da5412857",
  "timestamp" : 1565344010000,
  "analyzed" : false,
  "author" : "maximAtanasov",
  "authorEmail" : "Maksim.Atanasov@adesso.de",
  "comment" : "move GetMetricsForCommitCommand.java"
}, {
  "hash" : "c113e1d39183da5a",
  "timestamp" : 1565266154000,
  "analyzed" : false,
  "author" : "maximAtanasov",
  "authorEmail" : "Maksim.Atanasov@adesso.de",
  "comment" : "delete AnalyzingJobRename.java"
}, {
  "hash" : "da3cb1254c0a0a1f",
  "timestamp" : 1565262980000,
  "analyzed" : false,
  "author" : "maximAtanasov",
  "authorEmail" : "Maksim.Atanasov@adesso.de",
  "comment" : "remove MetricValue.java"
}, {
  "hash" : "1933c99825e8b50a",
  "timestamp" : 1565262963000,
  "analyzed" : false,
  "author" : "maximAtanasov",
  "authorEmail" : "Maksim.Atanasov@adesso.de",
  "comment" : "rename Finding.java"
}, {
  "hash" : "ac59bac061800203",
  "timestamp" : 1565248394000,
  "analyzed" : false,
  "author" : "maximAtanasov",
  "authorEmail" : "Maksim.Atanasov@adesso.de",
  "comment" : "add GetMetricsForCommitCommand.java"
}, {
  "hash" : "1df7d307cf41f753",
  "timestamp" : 1565012161000,
  "analyzed" : false,
  "author" : "maximAtanasov",
  "authorEmail" : "Maksim.Atanasov@adesso.de",
  "comment" : "add MetricValue.java"
}, {
  "hash" : "7d95f61ba5a8f2cc",
  "timestamp" : 1565005871000,
  "analyzed" : false,
  "author" : "maximAtanasov",
  "authorEmail" : "Maksim.Atanasov@adesso.de",
  "comment" : "modify Finding.java"
}, {
  "hash" : "93e1d2a50811e99d",
  "timestamp" : 1565005823000,
  "analyzed" : false,
  "author" : "maximAtanasov",
  "authorEmail" : "Maksim.Atanasov@adesso.de",
  "comment" : "rename AnalyzingJob.java"
}, {
  "hash" : "2c37909c99f45183",
  "timestamp" : 1565005785000,
  "analyzed" : false,
  "author" : "maximAtanasov",
  "authorEmail" : "Maksim.Atanasov@adesso.de",
  "comment" : "add AnalyzingJob.java"
}, {
  "hash" : "fd68136dd6489504",
  "timestamp" : 1565005560000,
  "analyzed" : false,
  "author" : "maximAtanasov",
  "authorEmail" : "Maksim.Atanasov@adesso.de",
  "comment" : "add Finding.java"
} ]

5.2.3. Listing commits for a given contributor

An additional email parameter may be supplied to this request to only return the commits authored by the matching contributor.

Example Request
GET /api/projects/2074/commits?email=Kilian.Krause@adesso.de&branchName=master HTTP/1.1
Content-Type: application/json
Host: localhost:8080
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 213

[ {
  "hash" : "e9f7ff6fdd8c0863",
  "timestamp" : 1584013941000,
  "analyzed" : false,
  "author" : "Krause",
  "authorEmail" : "Kilian.Krause@adesso.de",
  "comment" : "modify testModule1/NewRandomFile.java"
} ]

5.2.4. Listing a Project’s Commits as a Git log

Response Structure
Path Type Description

[]

Array

Array of the commits in this project in a git log similar format.

[].refs

Array

Array of strings with the refs pointing to the commit

[].hash

String

The hash of the commit.

[].parents

Array

Array of strings with the parents of the commit

[].author

Object

Object containing author information about the commit.

[].author.name

String

The name of the author

[].author.email

String

The email of the author

[].author.timestamp

Number

The timestamp of the commit

[].subject

String

The comment of this commit truncated to the first 100 characters.

[].analyzed

Boolean

Whether this commit is already analyzed or not.
Example Request
GET /api/projects/66/commitLog HTTP/1.1
Content-Type: application/json
Host: localhost:8080
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 4187

[ {
  "refs" : [ "master" ],
  "hash" : "e9f7ff6fdd8c0863",
  "parents" : [ "d3272b3793bc4b2b" ],
  "author" : {
    "name" : "Krause",
    "email" : "Kilian.Krause@adesso.de",
    "timestamp" : 1584013941000
  },
  "subject" : "modify testModule1/NewRandomFile.java",
  "analyzed" : false
}, {
  "refs" : [ "testBranch2" ],
  "hash" : "fcd9a0e7c34086fd",
  "parents" : [ "d3272b3793bc4b2b" ],
  "author" : {
    "name" : "Atanasov",
    "email" : "Maksim.Atanasov@adesso.de",
    "timestamp" : 1582619029000
  },
  "subject" : "added TestFile.java",
  "analyzed" : false
}, {
  "refs" : [ "testBranch1" ],
  "hash" : "d3272b3793bc4b2b",
  "parents" : [ "251dc2fde2db8d9a" ],
  "author" : {
    "name" : "maximAtanasov",
    "email" : "Maksim.Atanasov@adesso.de",
    "timestamp" : 1565615004000
  },
  "subject" : "testCommit",
  "analyzed" : false
}, {
  "refs" : [ ],
  "hash" : "251dc2fde2db8d9a",
  "parents" : [ "b7be4fc8d394e296" ],
  "author" : {
    "name" : "maximAtanasov",
    "email" : "Maksim.Atanasov@adesso.de",
    "timestamp" : 1565598255000
  },
  "subject" : "modify GetMetricForCommitCommand.java",
  "analyzed" : false
}, {
  "refs" : [ ],
  "hash" : "b7be4fc8d394e296",
  "parents" : [ "53e2f71da5412857" ],
  "author" : {
    "name" : "maximAtanasov",
    "email" : "Maksim.Atanasov@adesso.de",
    "timestamp" : 1565594249000
  },
  "subject" : "remove FindingRename.java",
  "analyzed" : false
}, {
  "refs" : [ ],
  "hash" : "53e2f71da5412857",
  "parents" : [ "c113e1d39183da5a" ],
  "author" : {
    "name" : "maximAtanasov",
    "email" : "Maksim.Atanasov@adesso.de",
    "timestamp" : 1565344010000
  },
  "subject" : "move GetMetricsForCommitCommand.java",
  "analyzed" : false
}, {
  "refs" : [ ],
  "hash" : "c113e1d39183da5a",
  "parents" : [ "da3cb1254c0a0a1f" ],
  "author" : {
    "name" : "maximAtanasov",
    "email" : "Maksim.Atanasov@adesso.de",
    "timestamp" : 1565266154000
  },
  "subject" : "delete AnalyzingJobRename.java",
  "analyzed" : false
}, {
  "refs" : [ ],
  "hash" : "da3cb1254c0a0a1f",
  "parents" : [ "1933c99825e8b50a" ],
  "author" : {
    "name" : "maximAtanasov",
    "email" : "Maksim.Atanasov@adesso.de",
    "timestamp" : 1565262980000
  },
  "subject" : "remove MetricValue.java",
  "analyzed" : false
}, {
  "refs" : [ ],
  "hash" : "1933c99825e8b50a",
  "parents" : [ "ac59bac061800203" ],
  "author" : {
    "name" : "maximAtanasov",
    "email" : "Maksim.Atanasov@adesso.de",
    "timestamp" : 1565262963000
  },
  "subject" : "rename Finding.java",
  "analyzed" : false
}, {
  "refs" : [ ],
  "hash" : "ac59bac061800203",
  "parents" : [ "1df7d307cf41f753" ],
  "author" : {
    "name" : "maximAtanasov",
    "email" : "Maksim.Atanasov@adesso.de",
    "timestamp" : 1565248394000
  },
  "subject" : "add GetMetricsForCommitCommand.java",
  "analyzed" : false
}, {
  "refs" : [ ],
  "hash" : "1df7d307cf41f753",
  "parents" : [ "7d95f61ba5a8f2cc" ],
  "author" : {
    "name" : "maximAtanasov",
    "email" : "Maksim.Atanasov@adesso.de",
    "timestamp" : 1565012161000
  },
  "subject" : "add MetricValue.java",
  "analyzed" : false
}, {
  "refs" : [ ],
  "hash" : "7d95f61ba5a8f2cc",
  "parents" : [ "93e1d2a50811e99d" ],
  "author" : {
    "name" : "maximAtanasov",
    "email" : "Maksim.Atanasov@adesso.de",
    "timestamp" : 1565005871000
  },
  "subject" : "modify Finding.java",
  "analyzed" : false
}, {
  "refs" : [ ],
  "hash" : "93e1d2a50811e99d",
  "parents" : [ "2c37909c99f45183" ],
  "author" : {
    "name" : "maximAtanasov",
    "email" : "Maksim.Atanasov@adesso.de",
    "timestamp" : 1565005823000
  },
  "subject" : "rename AnalyzingJob.java",
  "analyzed" : false
}, {
  "refs" : [ ],
  "hash" : "2c37909c99f45183",
  "parents" : [ "fd68136dd6489504" ],
  "author" : {
    "name" : "maximAtanasov",
    "email" : "Maksim.Atanasov@adesso.de",
    "timestamp" : 1565005785000
  },
  "subject" : "add AnalyzingJob.java",
  "analyzed" : false
}, {
  "refs" : [ ],
  "hash" : "fd68136dd6489504",
  "parents" : [ ],
  "author" : {
    "name" : "maximAtanasov",
    "email" : "Maksim.Atanasov@adesso.de",
    "timestamp" : 1565005560000
  },
  "subject" : "add Finding.java",
  "analyzed" : false
} ]

5.3. Commit Metric Values

You can access the metric values aggregated for each commit using this operation. You have to specify a query object that defines which metrics you are interested in.

Metric values will become available as soon as an Analyzing Job starts for your project. At that moment, analysis of each commit defined in the job starts. Depending on how many commits that are and how many analyzers are configured, analysis will take a while.

5.3.1. Querying Metric Values of a Commit

Query Structure
Path Type Description

commit

String

The Name of the commit whose metric values to get.

metrics

Array

List of the names of the metrics whose values you want to query.
Example Request

This request can be sent using either the GET or the POST method. See Usage of GET.

 
GET /api/projects/1512/metricvalues/perCommit HTTP/1.1
Content-Type: application/json
Content-Length: 188
Host: localhost:8080

{
  "commit" : "d3272b3793bc4b2bc36a1a3a7c8293fcf8fe27df",
  "metrics" : [ "coderadar:size:loc:java", "coderadar:size:sloc:java", "coderadar:size:cloc:java", "coderadar:size:eloc:java" ]
}
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 195

[ {
  "metricName" : "coderadar:size:eloc:java",
  "value" : 8
}, {
  "metricName" : "coderadar:size:sloc:java",
  "value" : 15
}, {
  "metricName" : "coderadar:size:loc:java",
  "value" : 18
} ]

5.3.2. Querying File content, metric values and findings of a file in a commit.

Request Structure
Path Type Description

commitHash

String

The commit whose file tree to search in.

filepath

String

The path of the file
Response Structure
Path Type Description

content

String

The content of the file as a string

metrics

Array

A list of metrics containing the metrics name, value and location in the file
Example Request

This request can be sent using either the GET or the POST method. See Usage of GET.

 
GET /api/projects/16/files/content HTTP/1.1
Content-Type: application/json
Content-Length: 113
Host: localhost:8080

{
  "commitHash" : "d3272b3793bc4b2bc36a1a3a7c8293fcf8fe27df",
  "filepath" : "GetMetricsForCommitCommand.java"
}
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 735

{
  "content" : "package io.reflectoring.coderadar.query.port.driver;\n\nimport lombok.AllArgsConstructor;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\nimport javax.validation.constraints.NotEmpty;\nimport javax.validation.constraints.NotNull;\nimport java.util.List;\n\n@Data\n@NoArgsConstructor\n@AllArgsConstructor\npublic class GetMetricsForCommitCommand {\n  @NotNull @NotEmpty String commitChange;\n  @NotNull List<String> metrics;\n}\n",
  "metrics" : [ {
    "name" : "coderadar:size:eloc:java",
    "value" : 7,
    "findings" : [ ]
  }, {
    "name" : "coderadar:size:sloc:java",
    "value" : 14,
    "findings" : [ ]
  }, {
    "name" : "coderadar:size:loc:java",
    "value" : 17,
    "findings" : [ ]
  } ]
}

5.3.3. Querying the file diff against the same file in the first commit parent.

Request Structure
Path Type Description

commitHash

String

The commit whose file tree to search in.

filepath

String

The path of the file
Response Structure
Path Type Description

content

String

The diff against the same file in the parent commit

metrics

Null

Always null
Example Request

This request can be sent using either the GET or the POST method. See Usage of GET.

 
GET /api/projects/660/files/diff HTTP/1.1
Content-Type: application/json
Content-Length: 112
Host: localhost:8080

{
  "commitHash" : "e9f7ff6fdd8c0863fdb5b24c9ed35a3651e20382",
  "filepath" : "testModule1/NewRandomFile.java"
}
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 160

{
  "content" : "@@ -1 +1,2 @@\n public class this does not compile\n+// This test still does not compile\n\\ No newline at end of file\n",
  "metrics" : null
}

5.4. Metrics Trees

5.4.1. Querying Metrics for all Files in a Single Commit

This endpoint provides a tree structure containing metrics for all modules and files of the project at the time of a specified commit.

Request Structure
Path Type Description

commit

String

Commit to get the metrics for.

metrics

Array

List of Metrics to query.
Response Structure
Path Type Description

name

String

The name of the file or module, containing the full path.

type

String

Either 'MODULE' if this node describes a module which can have child nodes or 'FILE' if this node describes a file (which has no child nodes).

metrics

Array

Contains a map of metric values for each of the metrics specified in the query at the time of the commit specified in the request. If this node is a MODULE, the metrics are aggregated over all files within this module.

children

Array

If this node describes a MODULE, this field contains the list of child nodes of the same structure, which can be of type MODULE or FILE.
Example Request

This request can be sent using either the GET or the POST method. See Usage of GET.

 
GET /api/projects/240/metricvalues/tree HTTP/1.1
Content-Type: application/json
Content-Length: 188
Host: localhost:8080

{
  "commit" : "d3272b3793bc4b2bc36a1a3a7c8293fcf8fe27df",
  "metrics" : [ "coderadar:size:loc:java", "coderadar:size:sloc:java", "coderadar:size:cloc:java", "coderadar:size:eloc:java" ]
}
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 979

{
  "name" : "root",
  "type" : "MODULE",
  "metrics" : [ {
    "metricName" : "coderadar:size:eloc:java",
    "value" : 8
  }, {
    "metricName" : "coderadar:size:sloc:java",
    "value" : 15
  }, {
    "metricName" : "coderadar:size:loc:java",
    "value" : 18
  } ],
  "children" : [ {
    "name" : "GetMetricsForCommitCommand.java",
    "type" : "FILE",
    "metrics" : [ {
      "metricName" : "coderadar:size:eloc:java",
      "value" : 7
    }, {
      "metricName" : "coderadar:size:sloc:java",
      "value" : 14
    }, {
      "metricName" : "coderadar:size:loc:java",
      "value" : 17
    } ],
    "children" : [ ]
  }, {
    "name" : "testModule1/NewRandomFile.java",
    "type" : "FILE",
    "metrics" : [ {
      "metricName" : "coderadar:size:eloc:java",
      "value" : 1
    }, {
      "metricName" : "coderadar:size:sloc:java",
      "value" : 1
    }, {
      "metricName" : "coderadar:size:loc:java",
      "value" : 1
    } ],
    "children" : [ ]
  } ]
}

5.4.2. Querying Metrics for all Files in two Commits

This endpoint provides a tree structure containing metrics for all modules and files of the project at the time of two specified commits so the metric values between these commits can be directly compared. Also, the tree contains information about files that have been renamed or moved between the two specified commits.

Request Structure
Path Type Description

commit1

String

First commit to get the metrics for.

commit2

String

Second commit to get the metrics for.

metrics

Array

List of Metrics to query.
Response Structure
Path Type Description

name

String

The name of the file or module, containing the full path.

type

String

Either 'MODULE' if this node describes a module which can have child nodes or 'FILE' if this node describes a file (which has no child nodes).

commit1Metrics

Array

Contains a map of metric values for each of the metrics specified in the query at the time of the commit specified in the request. If this node is a MODULE, the metrics are aggregated over all files within this module.

commit2Metrics

Array

Contains a map of metric values for each of the metrics specified in the query at the time of the commit specified in the request. If this node is a MODULE, the metrics are aggregated over all files within this module.

children

Array

If this node describes a MODULE, this field contains the list of child nodes of the same structure, which can be of type MODULE or FILE.

renamedFrom

String

The old path of the file, if it was renamed. Null otherwise. This attribute is only set for the new file.

renamedTo

String

The new path of the file, if it was renamed. Null otherwise. This attribute is only set for the old file.

changes

Changes

One of the following changes or none of them: 'renamed', 'modified', 'added', 'deleted'.
Example Request

This request can be sent using either the GET or the POST method. See Usage of GET.

 
GET /api/projects/241/metricvalues/deltaTree HTTP/1.1
Content-Type: application/json
Content-Length: 247
Host: localhost:8080

{
  "commit1" : "fd68136dd6489504e829b11f2fce1fe97c9f5c0c",
  "commit2" : "d3272b3793bc4b2bc36a1a3a7c8293fcf8fe27df",
  "metrics" : [ "coderadar:size:loc:java", "coderadar:size:sloc:java", "coderadar:size:cloc:java", "coderadar:size:eloc:java" ]
}
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2239

{
  "name" : "root",
  "type" : "MODULE",
  "commit1Metrics" : [ {
    "metricName" : "coderadar:size:eloc:java",
    "value" : 8
  }, {
    "metricName" : "coderadar:size:sloc:java",
    "value" : 10
  }, {
    "metricName" : "coderadar:size:loc:java",
    "value" : 12
  } ],
  "commit2Metrics" : [ {
    "metricName" : "coderadar:size:eloc:java",
    "value" : 8
  }, {
    "metricName" : "coderadar:size:sloc:java",
    "value" : 15
  }, {
    "metricName" : "coderadar:size:loc:java",
    "value" : 18
  } ],
  "renamedFrom" : null,
  "renamedTo" : null,
  "changes" : null,
  "children" : [ {
    "name" : "Finding.java",
    "type" : "FILE",
    "commit1Metrics" : [ {
      "metricName" : "coderadar:size:eloc:java",
      "value" : 8
    }, {
      "metricName" : "coderadar:size:sloc:java",
      "value" : 10
    }, {
      "metricName" : "coderadar:size:loc:java",
      "value" : 12
    } ],
    "commit2Metrics" : null,
    "renamedFrom" : null,
    "renamedTo" : null,
    "changes" : {
      "renamed" : false,
      "modified" : false,
      "deleted" : true,
      "added" : false
    },
    "children" : [ ]
  }, {
    "name" : "GetMetricsForCommitCommand.java",
    "type" : "FILE",
    "commit1Metrics" : null,
    "commit2Metrics" : [ {
      "metricName" : "coderadar:size:eloc:java",
      "value" : 7
    }, {
      "metricName" : "coderadar:size:sloc:java",
      "value" : 14
    }, {
      "metricName" : "coderadar:size:loc:java",
      "value" : 17
    } ],
    "renamedFrom" : null,
    "renamedTo" : null,
    "changes" : {
      "renamed" : false,
      "modified" : false,
      "deleted" : false,
      "added" : true
    },
    "children" : [ ]
  }, {
    "name" : "testModule1/NewRandomFile.java",
    "type" : "FILE",
    "commit1Metrics" : null,
    "commit2Metrics" : [ {
      "metricName" : "coderadar:size:eloc:java",
      "value" : 1
    }, {
      "metricName" : "coderadar:size:sloc:java",
      "value" : 1
    }, {
      "metricName" : "coderadar:size:loc:java",
      "value" : 1
    } ],
    "renamedFrom" : null,
    "renamedTo" : null,
    "changes" : {
      "renamed" : false,
      "modified" : false,
      "deleted" : false,
      "added" : true
    },
    "children" : [ ]
  } ]
}

5.5. Files

5.5.1. Querying the file tree of a particular commit.

Response Structure
Path Type Description

path

String

The path or filename of the current node

children

Array

Contains any subdirectories and files in the current path
Example Request
GET /api/projects/33/files/tree/d3272b3793bc4b2bc36a1a3a7c8293fcf8fe27df?changedOnly=false HTTP/1.1
Host: localhost:8080
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 190

{
  "path" : "/",
  "children" : [ {
    "path" : "GetMetricsForCommitCommand.java",
    "children" : null
  }, {
    "path" : "testModule1/NewRandomFile.java",
    "children" : null
  } ]
}

6. Contributors

6.1. Structure

Path Type Description

id

Number

The id of the contributor.

displayName

String

The display name of the contributor.

names

Array

Different names that appear in different commits, but all belong to this contributor.

emailAddresses

Array

Different email addresses of the contributor.

6.2. List all contributors of a project

Example Request

GET /api/projects/395/contributors HTTP/1.1
Content-Type: application/json
Host: localhost:8080

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 278

[ {
  "id" : 396,
  "displayName" : "Krause",
  "names" : [ "Krause" ],
  "emailAddresses" : [ "kilian.krause@adesso.de" ]
}, {
  "id" : 397,
  "displayName" : "maximAtanasov",
  "names" : [ "maximAtanasov", "Atanasov" ],
  "emailAddresses" : [ "maksim.atanasov@adesso.de" ]
} ]

Response Structure

Path Type Description

[]

Array

Array of all contributors in this project

[].id

Number

The id of the contributor

[].displayName

String

Display name of the contributor

[].names

Array

Set of names that the contributor has used in git commits

[].emailAddresses

Array

Set of email addresses of the contributor

6.3. List all contributors for a given path

Example Request for a File

GET /api/projects/362/contributors/path HTTP/1.1
Content-Type: application/json
Content-Length: 109
Host: localhost:8080

{
  "path" : "GetMetricsForCommitCommand.java",
  "commitHash" : "e9f7ff6fdd8c0863fdb5b24c9ed35a3651e20382"
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 154

[ {
  "id" : 364,
  "displayName" : "maximAtanasov",
  "names" : [ "maximAtanasov", "Atanasov" ],
  "emailAddresses" : [ "maksim.atanasov@adesso.de" ]
} ]

Example Request for a Directory

GET /api/projects/329/contributors/path HTTP/1.1
Content-Type: application/json
Content-Length: 89
Host: localhost:8080

{
  "path" : "testModule1",
  "commitHash" : "e9f7ff6fdd8c0863fdb5b24c9ed35a3651e20382"
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 278

[ {
  "id" : 330,
  "displayName" : "Krause",
  "names" : [ "Krause" ],
  "emailAddresses" : [ "kilian.krause@adesso.de" ]
}, {
  "id" : 331,
  "displayName" : "maximAtanasov",
  "names" : [ "maximAtanasov", "Atanasov" ],
  "emailAddresses" : [ "maksim.atanasov@adesso.de" ]
} ]

6.4. Get single contributor

Example request

GET /api/contributors/429 HTTP/1.1
Content-Type: application/json
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 122

{
  "id" : 429,
  "displayName" : "Krause",
  "names" : [ "Krause" ],
  "emailAddresses" : [ "kilian.krause@adesso.de" ]
}

6.5. Merge contributors

Request Structure

Path Type Description

contributorIds

Array

The IDs of the contributors to merge. The ID of the first contributor in the list will be the ID of the merged contributor. All other IDs become invalid.

displayName

String

The new display name of the merged contributor.

Example Request

POST /api/contributors/merge HTTP/1.1
Content-Type: application/json
Content-Length: 63
Host: localhost:8080

{
  "contributorIds" : [ 297, 298 ],
  "displayName" : "Test"
}

Example Response

HTTP/1.1 200 OK

6.6. Update a Contributor

Request Structure

Path Type Description

displayName

String

The new display name of the contributor.

Example Request

POST /api/contributors/264 HTTP/1.1
Content-Type: application/json
Content-Length: 39
Host: localhost:8080

{
  "displayName" : "New DisplayName"
}

Example Response

HTTP/1.1 200 OK

7. Coderadar Core Metrics

7.1. Get Critical Files of a Project

7.1.1. Files With Many Contributors

Request Structure
Path Type Description

commitHash

String

Only search for critical files in the file tree of the given commit.

numberOfContributors

Number

The amount of contributors for which a file is considered critical.
Example Request
GET /api/projects/559/files/critical?numOfContr=2 HTTP/1.1
Content-Type: application/json
Content-Length: 93
Host: localhost:8080

{
  "commitHash" : "e9f7ff6fdd8c0863fdb5b24c9ed35a3651e20382",
  "numberOfContributors" : 2
}
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 101

[ {
  "path" : "testModule1/NewRandomFile.java",
  "contributors" : [ "maximAtanasov", "Krause" ]
} ]

7.1.2. Frequently Changed Files

Request Structure
Path Type Description

commitHash

String

Only search for critical files in the file tree of the given commit.

startDate

Number

Start date of the time period.

frequency

Number

How often a file needs to be changed in the time period to be declared as critical.
Example Request
GET /api/projects/626/files/modification/frequency HTTP/1.1
Content-Type: application/json
Content-Length: 113
Host: localhost:8080

{
  "commitHash" : "e9f7ff6fdd8c0863fdb5b24c9ed35a3651e20382",
  "startDate" : 1582588800000,
  "frequency" : 1
}
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 294

[ {
  "path" : "testModule1/NewRandomFile.java",
  "commits" : [ {
    "hash" : "e9f7ff6fdd8c0863",
    "timestamp" : 1584013941000,
    "analyzed" : false,
    "author" : "Krause",
    "authorEmail" : "Kilian.Krause@adesso.de",
    "comment" : "modify testModule1/NewRandomFile.java"
  } ]
} ]

8. Teams

8.1. Creating a team

Path Type Description

name

String

The name of the team

userIds

Array

A list of user IDs to add to the newly created team

Example Request

POST /api/teams HTTP/1.1
Content-Type: application/json
Content-Length: 49
Host: localhost:8080

{
  "name" : "testTeam",
  "userIds" : [ 2215 ]
}

Example Response

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 17

{
  "id" : 2216
}

8.2. Updating a team

Path Type Description

name

String

The name of the team

userIds

Array

A list of user IDs to add to the team

Example Request

POST /api/teams/2231 HTTP/1.1
Content-Type: application/json
Content-Length: 50
Host: localhost:8080

{
  "name" : "testTeam2",
  "userIds" : [ 2229 ]
}

Example Response

HTTP/1.1 200 OK

8.3. Deleting a team

Example Request

DELETE /api/teams/2177 HTTP/1.1
Host: localhost:8080

Example Response

HTTP/1.1 200 OK

8.4. Add users to a team

Path Type Description

elements

Array

A list containing user IDs

Example Request

POST /api/teams/2192/users HTTP/1.1
Content-Type: application/json
Content-Length: 27
Host: localhost:8080

{
  "elements" : [ 2191 ]
}

Example Response

HTTP/1.1 200 OK

8.5. Remove users from a team

Path Type Description

elements

Array

A list containing user IDs

Example Request

DELETE /api/teams/2218/users HTTP/1.1
Content-Type: application/json
Content-Length: 27
Host: localhost:8080

{
  "elements" : [ 2217 ]
}

Example Response

HTTP/1.1 200 OK

8.6. Retrieve a single team

Example Request

GET /api/teams/2203 HTTP/1.1
Host: localhost:8080

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 59

{
  "id" : 2203,
  "name" : "testTeam",
  "members" : [ ]
}

8.7. List all teams

Example Request

GET /api/teams/ HTTP/1.1
Host: localhost:8080

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 63

[ {
  "id" : 2193,
  "name" : "testTeam",
  "members" : [ ]
} ]

8.8. Assign a team to a project

Path Type Description

role

String

The role of the team in the project

Example Request

POST /api/projects/2209/teams/2208 HTTP/1.1
Content-Type: application/json
Content-Length: 22
Host: localhost:8080

{
  "role" : "ADMIN"
}

Example Response

HTTP/1.1 200 OK

8.9. Remove a team from a project

Example Request

DELETE /api/projects/2183/teams/2184 HTTP/1.1
Host: localhost:8080

Example Response

HTTP/1.1 200 OK

8.10. List teams assigned to a project

Example Request

GET /api/projects/2227/teams HTTP/1.1
Host: localhost:8080

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 63

[ {
  "id" : 2228,
  "name" : "testTeam",
  "members" : [ ]
} ]

8.11. List teams a user is in

Example Request

GET /api/users/2197/teams HTTP/1.1
Host: localhost:8080

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 143

[ {
  "id" : 2196,
  "name" : "testTeam",
  "members" : [ {
    "id" : 2197,
    "username" : "testUser",
    "platformAdmin" : false
  } ]
} ]

8.12. List all projects for a team

Example Request

GET /api/teams/2201/projects HTTP/1.1
Host: localhost:8080

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 205

[ {
  "id" : 2200,
  "name" : "project",
  "vcsUsername" : "testUser",
  "vcsPassword" : null,
  "vcsUrl" : "https://valid.url",
  "startDate" : "2022-03-24T08:21:50.571+0000",
  "defaultBranch" : null
} ]