Thrift API
These APIs should be used by the clients connecting to the server to store and get results.
Any new client should only interact with the database through these APIs.
Table of Contents
Available APIs
Report server API
The report server API should be used by any client to view or store analysis results.
Authentication system API
The authentication layer is used for supporting privileged-access only access and permission management.
Product management system API
The product management layer is responsible for handling requests about the different products and their configuration.
API versioning
CodeChecker supports some backward compatibility between API versions.
The API version is automatically encoded into the POST
request URLs made by
Thrift in the following format:
http://example.com:8001/[product-name]/<API-version>/<API-service>
For example:
https://example.com:8001/Default/v6.0/CodeCheckerService
Executing make thrift
in the web folder of CodeChecker will automatically
build each API version to the build/
dir.
How to add new API versions
Minor API improvements
For minor changes, these changes should go into the existing API files,
with appropriate Thrift-based versioning for struct
s where necessary.
Minor version changes should not change the behaviour and the invocation of already existing functions, only extend the API:
- After implementing the changes to the existing API files and handlers,
you need to increase the
SUPPORTED_VERSIONS
tag incodechecker_web/shared/version.py
. This dict stores for each major version, which is the highest supported minor version. In this case, simply increase the number by1
. - Change the
web/server/www/scripts/version.js
file to represent the newest version, e.g.6.1
.
Major API changes
For major changes, a new API must be defined. Start by creating a full
copy of the previous version's API to a new folder, e.g. v7
.
NOTE! Make sure the
Authentication
service API contains thecheckAPIVersion
function. Each client is expected to call this function to test if the server accepts its version.
- The new API definition (
thrift
) files must have thenamespace
tag appropriately suffixed, e.g._v7
. - Register a new major version in the
SUPPORTED_VERSIONS
dict incodechecker_web/shared/version.py
, but do NOT change the previous major version's setting. The first minor version for every major version is0
, i.e.7.0
. - Change the
server/www/scripts/version.js
to use the newest API,7.0
in this case. - Change the imports used in
server/www/scripts/<site>/<site>.js
(<site>
iscodecheckerviewer
orproductlist
) to load the API client from the new version. Do the same with the Python code everywhere (including the tests) where API clients are used (client/codechecker_client
). - Implement requesting actions via the new API in the command-line and the Web client.
- In the server, implement the API handlers for the new version as separate Python modules.
import
these new API handlers to the server module, and in thedo_POST
method of the server, set up that API requests through major version7
are routed to be handled by these new handlers. (Keep the formatting of imported names akin to those already in the file.)
How to delete API versions
Only major API versions can be deleted.
- Remove the
thrift
API definition's folder from underapi
. - Delete the API handler code from the server's files, and the routing
declarations in the
do_POST
method. - In the
version.py
, remove this major version's entry from theSUPPORTED_VERSIONS
table.