Latest | Extension guide | Web API

Web API

Authenticating to the Web API

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), you can use the X-Sonar-Passcode authentication scheme.

With the bearer authentication scheme

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

A token of User type is generated in SonarQube Server UI.
See Managing your tokens.
It is provided through the Authorization: Bearer <myToken> header.
See Sample API request below.

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.

With the X-Sonar-Passcode authentication scheme

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:

curl --request GET \

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

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

Sending an API request

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.

Sample API request

If, for example, you want to use the Web API to extract measures, you can make a “GET MEASURES” call to the /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.

Request

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

Response

{
   "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"
         }
      ]
   }
}

Web API deprecation policy

The goal of the deprecation policy is to make sure that users are aware of what is changing and have time to adjust before a component of the API is dropped at a given planned date.

The Web API deprecation policy states that:

An API component must be deprecated before being dropped. Furthermore, if the underlying feature is not being dropped, a replacement component must immediately be provided.
A deprecated API component must be fully supported until its drop (For instance the implementation of a deprecated method can't be replaced by throwing a new UnsupportedOperationException()).
The API release cycle is tied to the SonarQube Server release cycle.
A deprecated API endpoint can be dropped in January of the year following the year it was deprecated, but not before 6 months after deprecation.

Under special circumstances, for example, when there are security vulnerabilities that need to be addressed, we might make an exception and drop the deprecated API component earlier.

This leads to the following policy recommendations for API users:

Regularly monitor the deprecation of API components and check if you’re currently using them. See Monitoring the deprecated API components.
If you're currently using deprecated API components:
- Don't add new uses of it.
- Make the necessary updates in your next few releases so you’re ready for any breaking changes after the next LTA release.

Notes

Code metrics

You can retrieve code metric values and histories by using the /api/measures endpoint. The metric keys are listed in the metric tables in Metric definitions, or you can use the /api/metrics endpoint to retrieve them.

Was this page helpful?