Why a new API?
SonarQube can be accessed through its graphical user interface or Web API. The Web API facilitates task automation and can be used to simplify integration of SonarQube with your ecosystem.
SonarQube’s Web API has served our users well for over a decade. Nevertheless, as time passed, it started to show some limitations and consistency issues.
Most Significant Pain Points of the Web API V1
- Naming Identifiers of different endpoints, objects, parameters, and response body elements are partially inconsistent. We sometimes use different names for the same data in other API locations.
- Source of truth Sometimes data is duplicated on several endpoints. There is no authoritative truth.
- Optimized for GUI The API endpoints were often designed and optimized for the needs of the graphical user interface. Unfortunately, they often do not match programmatic access requirements.
- HTTP codes HTTP response and error codes are not used consistently throughout the API.
- HTTP verbs Endpoints only use GET and POST.
All those factors negatively impact the discoverability of our API. Additionally, as the API follows an RPC style and no specific HTTP guidelines, it is difficult for third-party tools and users to interact with it.
Internally, the current API relies on an in-house framework. This framework has technical limitations, such as missing support for path parameters. It is costly to maintain, and endpoint declarations are excessively verbose. Last but not least, as the implementation is custom, it is less battle-tested. Consequently, the Sonar team wants to migrate away from the internal framework in favor of a widely used technology.
For all those users and technical-driven considerations, we decided to gradually retire the current API, in favor of a brand new API: The Web API v2.
The new Web API
With SonarQube 10.4, the first endpoints of the new Web API v2 were made public.
The API v2 will comply with the extensively adopted REST software architectural style to ease its discoverability. We are targeting REST maturity level 2 of the Richardson REST maturity level. Targeting level 2 allows us to rapidly deliver endpoints while providing the most descriptive contract allowed by REST and the HTTP protocol. As this wouldn't necessitate a backward-incompatible change at the contract level, we keep the possibility open to embrace HATEOAS (level 3) if there is traction. Supporting HATEOAS would improve the programmatic discovery of the API.
The API v2 comes with its dedicated documentation. On top of that, the contract is described following the OpenAPI specification. OpenAPI is a broadly adopted standard to document REST API contracts. It will help users auto-generate clients for different programming languages. Tools like Swagger can also consume the OpenAPI schema to auto-generate documentation and a graphical user interface to try out the API.
Following the REST guidelines, each endpoint of the API v2 will serve a specific resource and expose relevant HTTP verbs (GET/POST/PATCH and DELETE). The media type for requests and responses will be JSON.
With common REST APIs, it is often a puzzle for the users to understand whether they should use PUT or PATCH to modify a resource. Therefore, they need to read each endpoint's documentation to find the answer. We decided to support only PATCH for resource modifications to facilitate the API discovery.
PATCH allows partial and complete resource modifications, so it is more flexible than PUT. On the other hand, one of the main advantages of PUT is its requirement for idempotency. We decided to keep the best of both verbs and use PATCH with a constraint on idempotency - unless specified otherwise. The requirement for idempotency is an important reason why we use the JSON Merge Patch format (as defined in RFC-7396) to describe the request bodies sent to the PATCH endpoints.
Under the hood, the API v2 leverages the Spring WEB MVC framework. Although it may not be considered the trendiest framework, Spring WEB MVC is extensively used in the industry, offering a robust foundation built over years of development. Additionally, its wide usage ensures prompt resolution of any framework vulnerabilities that may arise. This enables us to concentrate our efforts on the business aspects of the application.
Migration timeline and deprecation
We want our users to benefit from the migrated endpoints as early as possible. For this reason, we plan to introduce API v2 endpoints gradually with each SonarQube release, opting for an incremental delivery approach rather than holding off until the entire migration to API v2 is complete. During this transition period, whenever we provide a new endpoint in the API v2, we will deprecate its API v1 equivalent. The deprecated endpoints will follow the general SonarQube deprecation policy. In other words, if an endpoint is deprecated in 10.X, you can continue to use it until the 10.Y LTS and it will be dropped in the 11.0 version.
In SonarQube 10.4, we also introduced Deprecation Logs to our product. These logs track all calls to deprecated endpoints, providing administrators with awareness to identify and migrate calls to the API v2 easily.
In the latest SonarQube release, we deprecated 15 endpoints of the API v1 in favor of API v2 endpoints. We are currently targeting SonarQube version 11.X LTS for the complete set of endpoints to be available in Web API v2. Please be mindful that this timeline is subject to change.
One API to rule them All…
Another frequent need of our API consumers is interoperability between the Web APIs of SonarQube and SonarCloud. We are addressing this with the API v2, and we will ensure that both products comply with the same API contracts for their API v2 endpoints.