# Web API

The web services composing the [web API](https://next.sonarqube.com/sonarqube/web_api) are documented within SonarQube Server. To access the documentation, select the help button from the top bar in SonarQube Server:

<div align="left"><figure><img src="https://content.gitbook.com/content/3VWSqvZ4eaBLWvA6epdv/blobs/1jitl9M8RhMBqIqaUC2Y/web-api-v2.png" alt="Accessing the Web API from SonarQube" width="241"><figcaption></figcaption></figure></div>

Note that the [Web API V2](https://next.sonarqube.com/sonarqube/web_api_v2) will gradually replace the Web API as endpoints get deprecated and replaced.

## Authenticating to the Web API <a href="#authenticate-to-api" id="authenticate-to-api"></a>

Administrative web services are secured and require the user to have specific permissions.

To authenticate to the Web API, we recommend that you use the bearer authentication scheme.

If you cannot use the bearer authentication scheme (e.g., with the API endpoint [monitoring/metrics](https://next.sonarqube.com/sonarqube/web_api/api/monitoring/metrics)), you can use the X-Sonar-Passcode authentication scheme.

<details>

<summary>With the bearer authentication scheme</summary>

With the bearer authentication scheme, a SonarQube Server token is used:

* A token of **User** type is generated in SonarQube Server UI.\
  See [managing-tokens](https://docs.sonarsource.com/sonarqube-server/user-guide/managing-tokens "mention").
* It is provided through the `Authorization: Bearer <myToken>` header.\
  See **Sample API request** below.

{% hint style="info" %}
If a token is used to interact with the API, a `SonarQube-Authentication-Token-Expiration` HTTP header is added to the response. This header contains the token expiration date and can help third-party tools track upcoming expirations; this method allows the token to be rotated in time.
{% endhint %}

</details>

<details>

<summary>With the X-Sonar-Passcode authentication scheme</summary>

With the X-Sonar-Passcode authentication scheme, a passcode is used:

* The passcode is defined:
  * Either in the `sonar.properties` configuration file as the value of the `sonar.web.systemPasscode` property.
  * Or through the `SONAR_WEB_SYSTEMPASSCODE` environment variable.
* The passcode is provided through the `X-Sonar-Passcode: <passcode>` header.

**Example**:

```css-79elbk
curl --request GET \

  --url 'https://sonarqube.com/api/monitoring/metrics \

  --header 'X-Sonar-Passcode: <passcode>'
```

</details>

## Sending an API request <a href="#send-api-request" id="send-api-request"></a>

To make a request, you need to find the HTTP method and the right path for the operation that you want to use.

It’s highly recommended to use form data parameters when making POST requests to the Web API. If you use URI query parameters instead then these parameters won’t be securely passed to the endpoint.

### Content-Type header

Unless the Sonar Web API endpoint specifications list a specific `Content-Type` value, your request should use the following `Content-Type` header:

`Content-Type: application/x-www-form-urlencoded`

This is the default `Content-Type` value set by most tools and libraries, such as `curl` and Python’s `requests` module, but you should check their documentation for proper usage.

## Sample API request <a href="#sample-api-request" id="sample-api-request"></a>

If, for example, you want to use the Web API to extract measures, you can make a "GET MEASURES" call to the [`/api/measures`](https://next.sonarqube.com/sonarqube/web_api/api/measures) endpoint to extract measures of a given metric for a given project. In the case of a private project, the user used to create the user-type token has the Browse permission on this project.

For this example, a possible request and response are shown below.

<details>

<summary>Request</summary>

```css-79elbk
curl --request GET \
  --url 'https://sonarqube.com/api/measures/component?metricKeys=ncloc%2Ccode_smells%2Ccomplexity&component=<myProjectKey>' \
  --header 'Authorization: Bearer <myToken>' 
```

</details>

<details>

<summary>Response</summary>

```css-79elbk
{
   "component": {
      "id": "id",
      "key": "my_project_key",
      "name": "my_project_name",
      "qualifier": "TRK",
      "measures": [
         {
            "metric": "complexity",
            "value": "4214"
         },
         {
            "metric": "code_smells",
            "value": "8595",
            "bestValue": false
         },
         {
            "metric": "ncloc",
            "value": "51667"
         }
      ]
   }
}
```

</details>

## Notes <a href="#notes" id="notes"></a>

### Code metrics <a href="#code-metrics" id="code-metrics"></a>

You can retrieve code metric values and histories by using the [`/api/measures`](https://next.sonarqube.com/sonarqube/web_api/api/measures)\`\`endpoint. The metric keys are listed in the metric tables in [metrics-definition](https://docs.sonarsource.com/sonarqube-server/user-guide/code-metrics/metrics-definition "mention"), or you can use the `/api/metrics` endpoint to retrieve them.

## Related pages <a href="#related-pages" id="related-pages"></a>

* [deprecation-policy](https://docs.sonarsource.com/sonarqube-server/server-update-and-maintenance/maintenance/deprecations/deprecation-policy "mention")