# 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 appending servicedoc.html to the base URL and opening the page in a web browser.

For a local test instance, the URL might look like this: http://localhost:8080/servicedoc.html.

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.

# 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

Most services will return JSON responses.

# Calling Conventions & Service Types

We differentiate between two types of services:

  • Project services allow querying data from a single project, for example the list of findings. These services need the project name as a parameter and thus, adhere to the URL form of p/[project-id]/[service-name].

  • Global services are not specific to a single project and can be used to query all projects of an instance. These services are called directly by appending the service name to the base URL.

Many services take their main argument (e.g., a code path) directly attached to the main URL. Some services also accept additional parameters that are passed using the HTTP convention: Parameters are separated by a ? from the main URL and separated by &.

# 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/projects"

To get the information about the configured metrics for a project with id mon:

curl --user bob:e434mikm35d "http://localhost:8080/p/mon/metric-schema"

And, finally, to get the actual metric values for a branch rel42 at timestamp 374343221 for the same project:

curl --user bob:e434mikm35d "http://localhost:8080/p/mon/metrics?t=rel42:374343221"

# Common pitfalls

Always make sure that you use the IDE 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.

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).