REST API
The Teamscale server exposes all of its functionality as REST web services. All functionality used in the Web UI and the IDE integrations is built upon these services and can also be used programmatically.
Available REST Services
The list of REST services is available from a running Teamscale instance by clicking on the icon at the top right and selecting API Reference.
Our public API is versioned, so you can call /api/v7.0.0/projects instead of /api/projects to receive the data model as of Teamscale 7.0.0 even when a future versions would return a different data model. Without a version the latest data model is returned. It is recommended to use the versioned API whenever possible.
To get an idea which service might be useful, you can also observe the calls made from the Web UI using the development tools of your web browser.
In case the necessary call is not shown in the documentation you can also switch to the internal services in the API reference to see the non-public services. However, we do not provide any guarantees on backwards compatibility for the internal services.
Authentication
Authentication for Teamscale's REST API happens via HTTP Basic Authentication and thus require a user name and the user's access key (not the password). The service call is then executed with the permissions of this user.
You can generate an access key on your profile page: <TEAMSCALE_URL>/user.html#access-key
A sample call using authentication using curl to https://demo.teamscale.com for user demo with an access key 7eSRFFOEUqO7NhhqDeyB1yEbUsMzZGDN would be:
curl --user demo:7eSRFFOEUqO7NhhqDeyB1yEbUsMzZGDN "https://demo.teamscale.com/api/health-check"Result representation
Services will return JSON responses.
Examples
For first experiments, the tool curl can be used to query services from the command line. For this we assume the service to be running on http://localhost:8080/, the user name to be bob and his access key to be e434mikm35d.
To get the list of all projects visible to the user, you can use
curl --user bob:e434mikm35d "http://localhost:8080/api/projects"To get the list of all findings for the project with ID mon:
curl --user bob:e434mikm35d "http://localhost:8080/api/projects/mon/findings/list?all=true"And, finally, to get the details for a single finding with specific ID for the same project:
curl --user bob:e434mikm35d "http://localhost:8080/api/projects/mon/findings/D83B237D487AB7DE656ED61CA7032DC6"Common pitfalls
Always make sure that you use the access key as password and not the actual password of the user when making REST calls. Also, the user needs to have sufficient permissions to view or change the corresponding data.
The branch information is usually passed in as parameter t in the format BRANCHNAME:TIMESTAMP (note the colon, which can stay unescaped in the URL), such as master:1597993879000. The timestamp is provided as milliseconds since the epoch (start of 1970), but you can also pass in the special value HEAD to get the latest data on the specified branch.
WARNING
Timestamps are in milliseconds, while many other tools might produce timestamps in seconds. Make sure to convert these before passing to Teamscale.
If something does not work as expected, you can often find additional information in the Service Log, which is available via the Web UI (System perspective).