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:

* :ref:`projects-list`
* :ref:`import-project-configuration`
* :ref:`export-project-configuration`
* :ref:`update-project-configuration`
* :ref:`single-project-details`
* :ref:`delete-project`
* :ref:`update-project-by-importing-development-teams`
* :ref:`projects-usage-activity`
* :ref:`project-get-default-role`
* :ref:`project-set-default-role`
* :ref:`project-get-role-mappings`
* :ref:`project-set-role-mappings`
* :ref:`project-delete-role-mappings`
* :ref:`get-project-architectural-components`
* :ref:`post-project-architectural-components`
* :ref:`analysis-list-of-a-project`
* :ref:`single-analysis-details`
* :ref:`files-list-from-an-analysis`
* :ref:`components-list-from-an-analysis`
* :ref:`single-components-details-from-an-analysis`
* :ref:`component-file-list-from-an-analysis`
* :ref:`commits-list-from-an-analysis`
* :ref:`issues-list-from-an-analysis`
* :ref:`commit-activity-trend-from-an-analysis`
* :ref:`author-statistics-from-an-analysis`
* :ref:`branch-statistics-from-an-analysis`
* :ref:`programming-language-experience-and-distribution`
* :ref:`delta-analysis-list-of-a-project`
* :ref:`single-delta-analysis-details`
* :ref:`groups-list`
* :ref:`projects-in-group-list`
* :ref:`group-get-default-role`
* :ref:`group-set-default-role`
* :ref:`group-get-role-mappings`
* :ref:`group-set-role-mappings`
* :ref:`group-delete-role-mappings`
* :ref:`users-list`
* :ref:`create-user`
* :ref:`get-user-by-username`
* :ref:`developer-settings-list`
* :ref:`teams-list`
* :ref:`create-team`
* :ref:`update-team`
* :ref:`delete-team`
* :ref:`developer-list`
* :ref:`update-developer`
* :ref:`delete developer`
* :ref:`remove-developer-from-team`
* :ref:`remove-developer-settings`
* :ref:`roles-list`
* :ref:`authentication-providers-list`
* :ref:`get-authentication-provider`
* :ref:`update-authentication-provider`
* :ref:`authentication-provider-role-mapping-list`
* :ref:`add-role-mapping-to-authentication-provider`
* :ref:`remove-role-mapping-from-authentication-provider`
* :ref:`authentication-provider-get-default-role`
* :ref:`authentication-provider-set-default-role`
* :ref:`get-project-pr-integration-with-webhooks-list`
* :ref:`update-project-pr-integration`
* :ref:`disable-project-pr-integration`
* :ref:`get-project-badge-status`
* :ref:`update-project-badge-status`
* :ref:`kpi-trends-endpoints`
* :ref:`pm-integration-endpoints`
* :ref:`maintenance-endpoints`
* :ref:`version-endpoints`


Using CodeScene's REST API
--------------------------

The REST API documentation URL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

| You can browse the REST API functions here `CodeScene RestAPI Functions </api/v2/docs>`_. Before trying any functionality, use the Authorize button then fill in your Personal Access Token to authenticate.
| The version in use is **v2**. Version v1 is deprecated

REST API authentication
~~~~~~~~~~~~~~~~~~~~~~~

| Any user with role Admin, Architect or RestApi can consume the REST API
| To consume the REST API, you need to authenticate using a Personal Access Token.

.. container:: alert-wrapper

   Deprecated Feature Alert

   .. rst-class:: description

   Using the REST API with basic auth is deprecated and will be removed in a future version. 


Filter queries
~~~~~~~~~~~~~~~~~

.. include:: ../../shared/integrations/filter-query.rst

Project endpoints
~~~~~~~~~~~~~~~~~

.. include:: ../../shared/integrations/projects-list.rst

.. _import-project-configuration:

Import Project Configuration
**********************************

.. code-block:: bash

    curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer <token>" \
    --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 CodeScene

- Minimal example for a project where you specify the local path ``./specifiy-path-project-config.json``

.. code-block:: 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``

.. code-block:: 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:

Export Project Configuration
**********************************

.. code-block:: bash

    curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    '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:

Update Project Configuration
**********************************

.. code-block:: bash

    curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    --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

.. code-block:: json

    {
      "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",
        "git-rename-limit": "int",
        "delivery-performance-release-tag": "string",
        "delta-recommend-review-level": "boolean",
        "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",
        "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",
        "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",
        "developer-configuration": "int"
      }
    }

.. include:: ../../shared/integrations/project-detail.rst

.. include:: ../../shared/integrations/project-delete.rst

.. include:: ../../shared/integrations/project-git-repository.rst

..  _add-git-repository-urls:

Add git repository url's (deprecated)
**************************************
.. code-block:: bash

    curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    --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:

.. code-block:: bash

    '{"urls":["https://mycompany.com/projects/p1.git", "https://mycompany.com/projects/p2.git"], \
    "generate-architectural-component":false }'

.. _update-project-by-importing-development-teams:

Update Project by importing development teams
***********************************************************
.. code-block:: bash

    curl -X POST -H 'Content-Type: text/csv' -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    --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 header

- Example file ``./teams.csv``

.. code-block:: bash

    author,team
    max,backend
    john,backend
    sherri,ui

.. _get-project-pr-integration-with-webhooks-list:

Get Project PR Integration with webhooks list
*********************************************

CodeScene support PR integration with following providers: github, bitbucket-server, gitlab, azure, github-app, bitbucket, gerrit

.. code-block:: bash

    curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    '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:

Update Project PR Integration
*****************************

Each provider require a custom configuration to be set.


**bitbucket-server example**

.. code-block:: bash

    curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    -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**

.. code-block:: bash

    curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    -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**

.. code-block:: bash

    curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    -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**

.. code-block:: bash

    curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    -d '{ \
          "github-app-id": "Specify the app id for the app you create on GitHub.", \
          "github-private-key": "The content of the .pem file you download by generating a private key for the app on GitHub.", \
          "github-secret": "Specify the webhook secret for the app you create on GitHub.", \
          "github-file-comments": "Set to none, review or annotations. Controls how the result will be presented on GitHub.", \
    }' 'http://localhost:3003/api/v2/projects/{project_id}/pr-integration/github-app'

**github-app example with global preset**

By creating a GitHub App settings preset, that preset can be reused for configuring PR integration in all projects
sharing the same GitHub App settings:

.. code-block:: bash

    curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    -d '{ \
          "github-preset-id": "Specify the id of a GitHub App settings preset."
          "github-file-comments": "Set to none, review or annotations. Controls how the result will be presented on GitHub.", \
    }' 'http://localhost:3003/api/v2/projects/{project_id}/pr-integration/github-app'

**bitbucket example**

.. code-block:: bash

    curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    -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 API Token with Pull requests read/write and Webhooks read/write scopes.", \
          "bitbucket-username": "Specify the Bitbucket user email address." \
    }' 'http://localhost:3003/api/v2/projects/{project_id}/pr-integration/bitbucket'

**gerrit example**

.. code-block:: bash

    curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    -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:

Disable Project PR Integration
******************************

.. code-block:: bash

    curl -X DELETE -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    'http://localhost:3003/api/v2/projects/{project_id}/pr-integration'

- Replace ``{project_id}`` with a valid id taken from the project list results.

.. include:: ../../shared/integrations/project-badges.rst

.. _projects-usage-activity:

Get Projects Usage Activity
*********************************************

Check the last time a specific project was accessed, the number of active authors, the duration of the last analysis

.. code-block:: bash

    curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    'http://localhost:3003/api/v2/projects/usage-activity'

.. _project-get-default-role:

Get Project Default Role
*********************************************

Get the default role for the given project id

.. code-block:: bash

    curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    'http://localhost:3003/api/v2/projects/{project_id}/default-role'

- Replace ``{project_id}`` with a valid id taken from the project list results.

.. _project-set-default-role:

Set Project Default Role
*********************************************

Set the default role for the given project id

.. code-block:: bash

    curl -X PUT -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    'http://localhost:3003/api/v2/projects/{project_id}/default-role/{role_id}'

- Replace ``{project_id}`` with a valid id taken from the project list results.
- Replace ``{role_id}`` with a valid id taken from the role list results.

.. include:: ../../shared/integrations/project-architectural-components.rst

.. _project-get-role-mappings:

Get Project Role Mappings
*********************************************

Get the authentication provider role mappings for given project id and authentication provider id

.. code-block:: bash

    curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    'http://localhost:3003/api/v2/projects/{project_id}/role-mappings/{provider_id}'

- Replace ``{project_id}`` with a valid id taken from the project list results.
- Replace ``{provider_id}`` with a valid id taken from the authentication providers list results.

.. _project-set-role-mappings:

Add Project Role Mappings
*********************************************

Add the authentication provider role mappings for given project id and authentication provider id

.. code-block:: bash

    curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' \
    -H "Authorization: Bearer <token>" -d '{ "identifier": "some_user", "role_id": {role_id}}' \
    'http://localhost:3003/api/v2/projects/{project_id}/role-mappings/{provider_id}'

- Replace ``{project_id}`` with a valid id taken from the project list results.
- Replace ``{provider_id}`` with a valid id taken from the authentication providers list results.
- Replace ``{role_id}`` with a valid id taken from the role list results.

.. _project-delete-role-mappings:

Remove Project Role Mappings
*********************************************

Remove the authentication provider role mappings for given project id and authentication provider id

.. code-block:: bash

    curl -X DELETE -H 'Content-Type: application/json' -H 'Accept: application/json' \
    -H "Authorization: Bearer <token>" -d '{ "identifier": "some_user"}' \
    'http://localhost:3003/api/v2/projects/{project_id}/role-mappings/{provider_id}'

- Replace ``{project_id}`` with a valid id taken from the project list results.
- Replace ``{provider_id}`` with a valid id taken from the authentication providers list results.

Analyses endpoints
~~~~~~~~~~~~~~~~~~

.. include:: ../../shared/integrations/analysis-list.rst

.. include:: ../../shared/integrations/single-analysis.rst

.. include:: ../../shared/integrations/analysis-file-list.rst

.. include:: ../../shared/integrations/component-list.rst

.. include:: ../../shared/integrations/single-component.rst

.. include:: ../../shared/integrations/component-file-list.rst

.. include:: ../../shared/integrations/commits-list.rst

.. include:: ../../shared/integrations/issues-list.rst

.. include:: ../../shared/integrations/commit-activity-trend.rst

.. include:: ../../shared/integrations/author-statistics.rst

.. include:: ../../shared/integrations/branch-statistics.rst

.. _programming-language-experience-and-distribution:

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:

1. How many developers know language X?
2. 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:

.. figure:: rest-api-contributions-example.png
   :alt: CodeScene calculates both total and relative contribution experience for each developer.
   :name: rest-api-contributions-example

   CodeScene calculates both total and relative contribution experience for each developer.

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:

| Get a list of all programming languages and active contributors with their relative contributions

.. code-block:: bash

    curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    'http://localhost:3003/api/v2/projects/{project-id}/analyses/latest/experience/languages'

| Limit the query to developers working in a specific programming language

.. code-block:: bash

    curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    '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:

| Get a list of all programming languages and active contributors with their relative contributions in a given component/sub-system

.. code-block:: bash

    curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    'http://localhost:3003/api/v2/projects/{project_id}/analyses/latest/components/{component}/experience/languages'

| Limit the query to developers working in a specific programming language within the given component/sub-system

.. code-block:: bash

    curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    '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.

.. include:: ../../shared/integrations/delta-analysis-list.rst

Groups endpoints
~~~~~~~~~~~~~~~~

.. _groups-list:

Groups list
***********

To call this endpoint you must be authenticated with an admin username.

.. code-block:: bash

    curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    'http://localhost:3003/api/v2/groups'


.. _projects-in-group-list:

Projects in group list
**********************

To call this endpoint you must be authenticated with an admin username.

.. code-block:: bash

    curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    'http://localhost:3003/api/v2/groups/{groups-id}/projects'

- Replace ``{groups-id}`` with a valid id taken from the groups list results.

.. _group-get-default-role:

Get Group Default Role
*********************************************

Get the default role for the given group id

.. code-block:: bash

    curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    'http://localhost:3003/api/v2/groups/{group_id}/default-role'

- Replace ``{group_id}`` with a valid id taken from the group list results.

.. _group-set-default-role:

Set Group Default Role
*********************************************

Set the default role for the given group id

.. code-block:: bash

    curl -X PUT -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    'http://localhost:3003/api/v2/groups/{group_id}/default-role/{role_id}'

- Replace ``{group_id}`` with a valid id taken from the group list results.
- Replace ``{role_id}`` with a valid id taken from the role list results.

.. _group-get-role-mappings:

Get Group Role Mappings
*********************************************

Get the authentication provider role mappings for given group id and authentication provider id

.. code-block:: bash

    curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    'http://localhost:3003/api/v2/groups/{group_id}/role-mappings/{provider_id}'

- Replace ``{group_id}`` with a valid id taken from the group list results.
- Replace ``{provider_id}`` with a valid id taken from the authentication providers list results.

.. _group-set-role-mappings:

Add Group Role Mappings
*********************************************

Add the authentication provider role mappings for given group id and authentication provider id

.. code-block:: bash

    curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' \
    -H "Authorization: Bearer <token>" -d '{ "identifier": "some_user", "role_id": {role_id}}' \
    'http://localhost:3003/api/v2/groups/{group_id}/role-mappings/{provider_id}'

- Replace ``{group_id}`` with a valid id taken from the group list results.
- Replace ``{provider_id}`` with a valid id taken from the authentication providers list results.
- Replace ``{role_id}`` with a valid id taken from the role list results.

.. _group-delete-role-mappings:

Remove Group Role Mappings
*********************************************

Remove the authentication provider role mappings for given group id and authentication provider id

.. code-block:: bash

    curl -X DELETE -H 'Content-Type: application/json' -H 'Accept: application/json' \
    -H "Authorization: Bearer <token>" -d '{ "identifier": "some_user"}' \
    'http://localhost:3003/api/v2/groups/{group_id}/role-mappings/{provider_id}'

- Replace ``{group_id}`` with a valid id taken from the group list results.
- Replace ``{provider_id}`` with a valid id taken from the authentication providers list results.

.. _users-list:

Users and Roles endpoints
~~~~~~~~~~~~~~~~~~~~~~~~~

Users list
*****************

To call this endpoint you must be authenticated with an admin username.

.. code-block:: bash

    curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    'http://localhost:3003/api/v2/users'

.. _create-user:

Create User
*****************

To call this endpoint you must be authenticated with an admin username.

.. code-block:: bash

    curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' \
    -H "Authorization: Bearer <token>" -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:

Get User by username
********************

To call this endpoint you must be authenticated with an admin username.

.. code-block:: bash

    curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    'http://localhost:3003/api/v2/users/{username}'

- Replace ``{username}`` with a valid username taken from the users list results.

.. _roles-list:

Roles list
**********

To call this endpoint you must be authenticated with an admin username.

.. code-block:: bash

    curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    'http://localhost:3003/api/v2/roles'

.. _authentication-providers-list:

Authentication providers list
*****************************

To call this endpoint you must be authenticated with an admin username.

.. code-block:: bash

    curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    'http://localhost:3003/api/v2/authentication-providers'

.. _get-authentication-provider:

Get authentication provider
***************************

To call this endpoint you must be authenticated with an admin username.

.. code-block:: bash

    curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    '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:

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

.. code-block:: bash

    curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    -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

.. code-block:: bash

    curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    -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:

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.

.. code-block:: bash

    curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    '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:

Add role mapping to authentication provider
*******************************************

To call this endpoint you must be authenticated with an admin username.

.. code-block:: bash

    curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' \
    -H "Authorization: Bearer <token>" -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`` and ``project_id`` parameters to add a mapping at the global level.
- use the ``group_id`` or ``project_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:

Remove role mapping from authentication provider
************************************************

To call this endpoint you must be authenticated with an admin username.

.. code-block:: bash

    curl -X DELETE -H 'Content-Type: application/json' -H 'Accept: application/json' \
    -H "Authorization: Bearer <token>" -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`` and ``project_id`` parameters to remove the mapping from the global level.
- use the ``group_id`` or ``project_id`` parameters to remove the mapping from group or project level.

.. _authentication-provider-get-default-role:

Get Authentication Provider Default Role
*********************************************

Get the default role for the given authentication provider id

.. code-block:: bash

    curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    'http://localhost:3003/api/v2/authentication-providers/{provider_id}/default-role'

- replace ``{provider_id}`` with a valid provider id taken from the authentication providers list results.

.. _authentication-provider-set-default-role:

Set Authentication Provider Default Role
*********************************************

Set the default role for the given authentication provider id

.. code-block:: bash

    curl -X PUT -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    'http://localhost:3003/api/v2/authentication-providers/{provider_id}/default-role/{role_id}'

- replace ``{provider_id}`` with a valid provider id taken from the authentication providers list results.
- replace ``{role_id}`` with a valid id taken from the role list results.

.. include:: ../../shared/integrations/developer-settings.rst

..
    then next line is part of developer-settings.rst but only for on-prem, must stay right after developer-settings.rst include

- to call this endpoint you must be authenticated with an admin username.

.. include:: ../../shared/integrations/kpi-trends.rst

.. include:: ../../shared/integrations/pm-integration.rst

.. include:: ../../shared/integrations/code-coverage-endpoints.rst

.. _maintenance-endpoints:

Maintenance endpoints
~~~~~~~~~~~~~~~~~~~~~~~~~

DB Backup
*****************

To call this endpoint you must be authenticated as an admin. This endpoint is intended to be used only if db engine is H2.

.. code-block:: bash

    curl -X POST -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    'http://localhost:3003/api/v2/maintenance/db-backup'

- the backup will generate a zip file in the same location as the original db file and will contain the timestamp in the name
- to get more information regarding the location of the database file see: `define-root-path-for-persistent-data <../getting-started/installation.html#define-root-path-for-persistent-data>`_.

.. _version-endpoints:

Version endpoint
~~~~~~~~~~~~~~~~~~~~~~~~~

Get the version information:

- running_version: the current running version
- latest_version: the latest version available for download

.. code-block:: bash

    curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer <token>" \
    'http://localhost:3003/api/v2/version'


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:

.. code-block:: bash

    call_api(){ curl -sS -H "Authorization: Bearer <token>" 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:

.. code-block:: bash

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

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

.. code-block:: bash

    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):

.. code-block:: bash

    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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can get the following information for every file analysed:

- path
- lines_of_code
- author_contributions_fragmentation
- goals
- name
- last_modification_age_in_months
- teams_contributions_fragmentation
- code_health
- language
- primary_team
- ownership_percentage
- number_of_authors
- cost
- number_of_defects
- recommendations
- team_ownership
- owner
- knowledge_loss_percentage
- number_of_teams
- change_frequency

CSV export of all files with their name, path, language and owner:

.. code-block:: bash

    #!/bin/bash
    page=1
    while : ; do
      result=`call_api /projects/1/analyses/latest/files\?page=${page}`
      if [[ "${result}" != *"error"* ]]; then
        maxpages=`echo ${result} | jq -r '.max_pages'`
        echo ${result} | jq -r '.files[] | [.name, .path, .language, .owner] | @csv'
      fi
      page=$((page+1))
      [[ ${page} -gt ${maxpages} ]] && break
    done

List the top hotspot files by change frequency:

.. code-block:: bash

    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:

.. code-block:: bash

    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:

.. code-block:: bash

    call_api /projects | jq -r '.projects[].id' | while read id;do call_api /projects/$id/export/configuration/json \
    | jq -r .config.analysisplan; done

Get a list of all the files having a supervise goal set and filetered by a path pattern

.. code-block:: bash

    page=1
    while : ; do
        result=`call_api /projects/100/analyses/latest/files\?filter=path~"my_custom_path"+goals.category:supervise\&page=${page}`
        if [[ "${result}" != *"error"* ]]; then
            maxpages=`echo ${result} | jq -r '.max_pages'`
            echo ${result} | jq -r '.files[] | [(now | strflocaltime("%F")), .path, .goals[].category, .code_health.current_score] | @csv'
        fi
        page=$((page+1))
        [[ ${page} -gt ${maxpages} ]] && break
    done

the example above is extracting data from project with id=100 and the files are filetered by path containing "my_custom_path",
goals category supervise and iterating through all the available pages, each like have a prefix with current data
and the output looks like the one below

.. code-block::

    "2023-10-25","my_custom_path/file1.ts","supervise",9.38
    "2023-10-25","my_custom_path/file2.ts","supervise",6.37
    "2023-10-25","my_custom_path/file3.ts","supervise",9.38
    "2023-10-25","my_custom_path/file4.ts","supervise",8.34


Code Health Analysis
~~~~~~~~~~~~~~~~~~~~

List the 100 most worked on files together with their code health trend, and sort by relevance:

.. code-block:: bash

    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:

.. code-block:: bash

    call_api /metadata/code-health-rules \
    | jq -r '.code_health_rules[] | [.code_health_rule] | @csv'

Architecture-Level Analysis Information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can get the following information for every component analysed:

- lines_of_code
- team_fragmentation_percentage
- name
- last_modification_age_in_months
- system_mastery
- language
- primary_team
- ownership_percentage
- number_of_authors
- cost
- team_ownership
- system_health
- owner
- knowledge_loss_percentage
- change_frequency
- code_coverage

CSV export of all components with their name, language owner and change_frequency:

.. code-block:: bash

    #!/bin/bash
    page=1
    while : ; do
      result=`call_api /projects/1/analyses/latest/components\?page=${page}`
      if [[ "${result}" != *"error"* ]]; then
        maxpages=`echo ${result} | jq -r '.max_pages'`
        refs=`echo ${result} | jq -r '.components[] | [.ref] | @csv'`
        for ref in $refs
        do
         component=`echo ${ref##*/} | rev | cut -c2- | rev`
         result=`call_api /projects/1/analyses/latest/components/${component}`
         if [[ "${result}" != *"error"* ]]; then
           echo "${result}" | jq -r '[.name, .language, .owner, .change_frequency] | @csv'
         fi
        done
      fi
      page=$((page+1))
      [[ ${page} -gt ${maxpages} ]] && break
    done

List a project's architectural components sort by name:

.. code-block:: bash

    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:

.. code-block:: bash

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

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

.. code-block:: bash

    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

- .. envvar:: CODESCENE_ANALYSIS_RESULTS_ROOT

  * "/path/to/analysis/"

- .. envvar:: CODESCENE_CLONED_REPOSITORIES_ROOT
  
  * "/path/to/repositories/"

**Example of create a new project using git repo URL and using environment variables**

.. code-block:: bash

    call_api /projects/new -X POST -H 'Content-Type: application/json' -H '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"

.. code-block:: bash

    call_api /projects/new -X POST -H 'Content-Type: application/json' -H '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 and existing developer configuration (using environment variables)**

.. code-block:: bash

    call_api /projects/new -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' \
        -d '{ "config": { "repo-paths": ["https://github.com/my-project/my-project-3.git"]} \
                          "developer-configuration": 10
            }'

This will create a project with name 'my-project-3' and reusing existing developer configuration with id = 10

Update Existing Project
~~~~~~~~~~~~~~~~~~~~~~~

**Example of setting group id for existing project**

.. code-block:: bash

    call_api /projects/1 -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' \
        -d '{ "config": { "group-id": 2}}'

This will set the group with id 2 to the project with id 1

**Example of setting developer configuration for existing project**

.. code-block:: bash

    call_api /projects/1 -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' \
        -d '{ "config": { "developer-configuration": 10}}'

This will set the developer-configuration with id 10 to the project with id 1
