Query Web API

The TIOBE TICS Web API is the public programming interface for the TICS viewer. It exposes the same metric data that the viewer uses, allowing you to integrate TICS data in your own management dashboard or reporting software.

Introduction

The API follows a RESTful design, meaning that you use stateless HTTP methods to request data. By using the HTTP protocol, you are not bound to a particular programming language or platform to consume the API. We recommend using a standard HTTP client library that is available for your programming language.

HTTP Request

Data is queried using an HTTP GET request on a particular URL. You can use a standard browser to experiment with the API. For example, to get the last measured value for the TIOBE Quality Indicator metric for project use the following Measure API URL:

The URL has the following variables:

 

The host name and port on which the TICS viewer runs.

 

The section that you want to request data for. In a default TICS installation there is only one section named TICS.

/v1

Indicates which version of the API you want to use. The version number is increased every time we have to make a backwards incompatible change to the API. This ensures that consumers of the old API do not break. New fields will be added to the API without increasing the version number, as this will not break existing consumers.

/Measure

The name of the API that you want to query. In this case the Measure API is consulted, which provides metric value data.

?metrics=tqi&filters=Project()

The part after '?' is called the query-string part of the URL and contains the API parameters. Each parameter is specified using a name=value pair. Multiple parameters are joined using '&'. Unrecognized parameters are silently ignored.

HTTP Response

If the request HTTP is valid and can be performed without problems, the API will return an HTTP status 200 response. The body of this response contains the requested data in JSON format. For the call above, this will look something like this:

{
  "data": [
    {
      "value": 77.39341858450899,
      "formattedValue": "77.39%",
      "letter": "C",
      "status": "PRESENT"
    }
  ],
  "metrics": [
    {
      "expression": "tqi",
      "fullName": "TQI"
    }
  ],
  "nodes": [
    {
      "name": "trunk",
      "fullPath": ""
    }
  ],
  "dates": [
    "2014-02-01T16:19:09.000+01:00"
  ]
}

If something went wrong, the status code 400 is used to indicate "expected errors". An example of an expected error is when you request data for a non-existent project. Status code 500 is used for unexpected errors. In this case, contact us and provide the resulting stack trace.

API Endpoints

The available API endpoints are now discussed in detail. For each endpoint we describe the input parameters that it accepts and the fields in the JSON output. Multiple values for an input parameter can be separated using commas (,). Parameter names and values are case-sensitive.

Currently there are four public endpoints available:

• The Measure API can be used to get (aggregated) numerical metric values.
• The Annotations API can be used to get annotations, which provide (non-aggregated) details on issues (e.g. coding standard violations) and other source facts (e.g. function complexity).
• The Quality Gate Status API can be used to query the quality gate status for a project.
• The ToImage API can be used to download an image of the TQI Label.

Measure API

Use the Measure API to obtain (aggregated) metric values one ore more projects, folders, or files, at a specific date. For example, to get the last measured value for the TIOBE Quality Indicator metric for project use the following URL:

The input query parameters are:

The JSON output fields are:

var idx = 0;
foreach(metric in json.metrics) {
  foreach(date in json.dates) {
    foreach(node in json.nodes) {
      var metricValue = json.data[idx];
      console.log('Value for metric %s, node %s at %s is %s', metric.fullName, node.fullPath, date, metricValue.formattedValue);
      idx += 1;
    }
  }
}

Annotations API

Use the Annotations API to retrieve annotation information for a particular metric and project. In contrast to the Measure API which is used to retrieve aggregated numerical metric data, the Annotations API gives information about the precise locations of issues or other source code facts, as is made available to the user through the Annotated Source view.

For instance, the following URL returns a JSON object containing all Coding Standard violations of level 1 for project :

GET 

The input parameters of the Annotations API are:

The JSON output fields are:

Examples

• To get all coding standard violations for a project for category 'Basic', you would do the following request:

  GET 

• To get all complexity annotations for a project for language C++, you would do the following request:

  GET 

  Note that summing the complexity of all returned annotations does not equal the Total Cyclomatic Complexity of the whole project. However, summing the decision counts (complexity-1) does equal the total decision count of whole project.

• To get all code duplication annotations for a project you would do the following request:

  GET 

• To get all code duplication annotations that are local within a file, you would do the following request:

  GET 

• To get all code duplication annotations that are external with respect to subsystems 'foo' and 'bar', you would do the following request:

  GET 

Quality Gate Status API

Use the Quality Gate API to query the status of the quality gate(s) that are defined for a particular project (and branch). Quality Gates are configured in the Administration Pages. For instance, to get the quality gate status for project and branch for the latest run, you would use the following URL:

GET 

The input parameters of the QualityGateStatus API are:

The JSON output fields are:

Examples

To get the quality gate result for project MYPROJECT including the details for the failing conditions, query: GET api/public/v1/QualityGateStatus?project=MYPROJECT&fields=details. Click here to show the example output.

{
  "passed": false,
  "message": "Project failed to pass quality gate",
  "url": "api/public/v1/QualityGateStatusDetails?axes\u003dProject(MYPROJECT),Date(1473230970)",
  "gates": [
    {
      "passed": false,
      "name": "Blocking coding Standard violations should not increase",
      "conditions": [
        {
          "passed": false,
          "error": false,
          "message": "Δ Coding Standard Violations for levels 1, 2, 3 should be at most 0 for each file with respect to 2016-09-02, but was not for 2 files",
          "details": {
            "itemTypes": [
              "file"
            ],
            "dataKeys": {
              "actualValue": {
                "title": "Coding Standard Violations",
                "order": 1,
                "itemType": "file"
              }
            },
            "itemCount": 2,
            "itemLimit": 100,
            "items": [
              {
                "itemType": "file",
                "name": "path/to/File1.c",
                "link": "AnnotatedSource.html#...",
                "data": {
                  "actualValue": {
                    "formattedValue": "+10",
                    "value": 10.0,
                    "classes": [
                      "delta-worse"
                    ]
                  }
                }
              },
              {
                "itemType": "file",
                "name": "other/path/to/File2.c",
                "link": "AnnotatedSource.html#...",
                "data": {
                  "actualValue": {
                    "formattedValue": "+1",
                    "value": 1.0,
                    "classes": [
                      "delta-worse"
                    ]
                  }
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

To get the quality gate result for project MYPROJECT, including links in the output to the Annotations API which allow you to query for detailed annotations, use query GET api/public/v1/QualityGateStatus?project=MYPROJECT&fields=annotationsApiV1Links. Click here to show the example output.

{
  "passed": false,
  "message": "Project failed to pass quality gate",
  "url": "api/public/v1/QualityGateStatusDetails?axes=Project(MYPROJECT),Date(1473230970)",
  "gates": [
    {
      "passed": false,
      "name": "CW absolute",
      "conditions": [
        {
          "passed": false,
          "error": false,
          "message": "Δ Compiler Warnings for levels 1, 2, 3 should be at most 0 for each file with respect to Last month, but was not for 14 files",
          "annotationsApiV1Links": [
            {
              "url": "api/public/v1/Annotations?filters=Date(1473230970),Project(MYPROJECT),Level(Set(1,2,3)),Where(Eq(Violations(CW),gt,0)),DeltaDate(default),IsNew(yes)&metric=Annotations(CW)"
            }
          ]
        }
      ]
    }
  ],
  "annotationsApiV1Links": [
    {
      "url": "api/public/v1/Annotations?filters=Date(1473230970),Project(MYPROJECT),Level(Set(1,2,3)),Where(Eq(Violations(CW),gt,0)),DeltaDate(default),IsNew(yes)&metric=Annotations(CW)"
    }
  ]
}

ToImage API

Use the ToImage endpoint to download the TQI Label as an image (png format) programmatically, or to embed the TQI Label in your own webpage:

GET 

To obtain a URL that you can use in your own application, go to the Dashboard and select the project and/or filters that you want to generate a TQI Label for. Then, right click the Download Image button beneath the TQI Label and choose "copy link address". You can use this URL in your application to download the TQI Label with the most actual data.

The parameters of the ToImage API are:

If you have configured authentication, you have to provide the required credentials using Basic HTTP Authentication. For instance, if you are using the GNU tool wget, you can provide a username and password as follows:

wget "ToImage?format=png&url=BASE64URL" --user USERNAME --password PASSWORD --auth-no-challenge -O TQILabel.png

Expressions

In this section we describe into more detail the different types of expressions that are used for the input parameters.

Metric expressions

A metric expression is used to specify which metric you want to retrieve data for. Typically, a metric expression consists of a single metric identifier, using the lower camel case naming convention. For example, you can use tqi to retrieve the TQI score or tqiCodingStd for the TQI Coding Standard score. Other metrics take one or more arguments. These metrics use the upper camel case convention. For instance, Violations(argument) is used to retrieve the number of violations, where the argument can be any of CS, CW, AI, SEC to retrieve the number of violations for coding standards, compiler warnings, abstract interpretation or security respectively. Other metrics take another metric as argument. The Delta and 'per KLOC' metrics are examples of this. For instance, to get the Number of Coding Standard Violations per KLOC, you would use the metric expression PerKloc(Violations(CS)).

A list of commonly used metric expressions is found below. Expressions for metrics that are not listed here can be found by opening a page such as the TQI Dashboard or Explorer and selecting the desired metrics in the metric picker. You will find the expressions for the selected metrics in the browser's address bar behind the query parameter named metrics or x (depending on the page).

Filter expressions

A filter is used to narrow down the data that you are interested in. Without any filters, a query aggregates all measurements across all projects into one metric value. A filter is specified using a case-sensitive filter expression, which has the form FilterName(parameter). The filter name determines what property of the measurement to filter on. The parameter specifies which measurements should pass the filter. For instance, Language(JAVA) is a filter that only keeps measurements that apply to Java files. Multiple filters can be specified by separating them using commas. For instance, Language(JAVA),CodeType(test) keeps measurements that apply to Java test files. See the table below for a list of available filters and examples.

Compound filters filter on a set of values, containing at least two elements. The are specified using a filter expression of the form FilterName(Set(parameter,parameter[,...])). For instance, Language(Set(CPP,JAVA)) is a filter that keeps measurements that apply to C++ or Java files. In the breadcrumb, a compound filter is created when you check multiple checkboxes in a filter dropdown menu.

Groupers are a kind of filter that causes a query to produce more than one result. We distinguish between open and closed groupers; the difference is the number of parameters. An open grouper doesn't accept any parameters and has the form FilterName(). It produces a metric value for each distinct property value it encounters. For instance, Language() produces a metric value per language that is encountered in the measurements. A closed grouper has at least two parameters: it produces a metric value for each parameter specified. For instance, Language(CS,JAVA) produces one metric value for C# and one for Java.

Below is an overview of supported filters that you can use with all API end points described here. The viewer uses additional filters that are not described here, but that you can find in your browser's address bar when selecting the filter in the breadcrumb. However, we do not recommend that you use these undocumented filters as they might change in the future.

Measure?metrics=loc&filters=Project(foo),Sub(src),Sub(main),Sub(java)

Measure?metrics=loc&filters=View(ORG),Project(foo),Sub(Team 2)

Date expressions

Date expressions are used inside the Date() and Run() filters, and as the second parameter in the Delta metric. The following date expressions are supported:

Path expression

A path expression denotes a single project, branch, folder or file and is a combination of a hierarchy specifier (HIE or ORG), followed by a comma-separated list of names. The first name is always the project name, the second name is the branch name. The remaining names denote folders. The last name can denote a file. For example, Path(HIE,MYPROJECT,trunk,path,to,file.cpp) denotes file named 'file.cpp' in folder 'path/to' in branch 'trunk', project 'MYPROJECT'. Path(HIE,MYPROJECT,trunk) denotes the root folder in the branch. Path(ORG,MYPROJECT,trunk) denotes the root folder of the same branch in the ORG hierarchy. The ORG hierarchy is only available if you have configured this view for your project.

Path literal

A path literal is an instance of a path expression that uses a different and deprecated syntax: HIE://MYPROJECT/trunk/path/to/file.cpp. This syntax has as limitation that branches with a forward slash in the name cannot be expressed, because the part after the / will be interpreted as a folder. Therefore, you should not use path literals as input, use the expression syntax instead. Unfortunately, the APIs do still output the ambiguous path literals, for backwards compatibility.

Cross-cutting concerns

In this section we discuss general API aspects, such as authentication.

Authentication

The Web API respects any authentication that you might have configured in your SERVER.yaml. If you try to acquire data for a project without providing proper credentials, the server responds with an HTTP status code 401: Unauthorized. Use HTTP basic access authentication to access projects that require authentication. Most HTTP client libraries support basic authentication. Please consult the documentation of the library that you use. The Web API uses HTTP realm "TICS".

Whichever client (library) you are using, please make sure that the credentials are supplied regardless of whether the server sends an "authentication challenge". When using wget for instance, it is important to specify the --auth-no-challenge flag, as follows:

wget URL --user USERNAME --password PASSWORD --auth-no-challenge

Cache generation and timeouts

After TICS finishes analysis of a project, it sends a notification to the viewer. The viewer needs time to generate caches for the new data. Depending on the size of the project and the server hardware, this might take a while, even up to an hour for very large projects. The Measure and Annotations API by default wait while cache generation for a project is active before returning results. This ensures that if you do an API call right after a TiCS analysis has finished, you will get the latest results, rather than the previous data.

Alternatively, you can use the query parameter wait=false to tell the API not to wait for cache generation to complete.

JSONP

When you try to access the WebAPI using JavaScript that is running in your browser, you will run into the browser's same-origin policy. This security policy prevents your script from accessing data on the TICS Viewer, because it is located on a different origin (the combination of hostname, port number, and URI scheme). To overcome this issue, the WebAPI supports JSONP. Another way to overcome the same-origin policy is Cross-origin resource sharing (CORS), but this is not yet supported by the TICS Viewer.

To use JSONP, you have to change the WebAPI URL to include a query parameter named callback, whose value is the name of a JavaScript function that is defined in your script. Instead of the normal JSON payload, the response will be a JavaScript function call to the specified function using the JSON payload as the function's argument. Libraries such as jQuery and Angular support the JSONP convention. Please refer to their respective documentation pages.

How To's

How to get a list of all projects or a list of all branches for a project?

To get a list of all projects, use the Measure API with metric none and group by Project:

The response is formatted like any other Measure API call. The data field of the response is not of interest, as we specified the none metric. However, the nodes field contains an array of path objects, one for each project that you have configured:

{
  "data": [{
      "formattedValue": null,
      "letter": null,
      "value": null,
      "total": 0,
      "success": 0
  }, ...],
  "dates": [
    "2014-04-17T10:40:33.541+02:00"
  ],
  "metrics": [{
      "expression": "none",
      "fullName": "-"
    }
  ],
  "nodes": [{
      "name": "MYPROJECT1",
      "fullPath": "HIE://MYPROJECT1"
    },
    {
      "name": "MYPROJECT2",
      "fullPath": "HIE://MYPROJECT2"
    },
    ...
  ]
}

The fullPath field can be used as input parameter for any follow-up Measure API calls. For example, to get a list of branches for project :

How to get a list of all runs for a project?

To get a list of timestamps of moments when an analysis was performed, use the Measure API with metric runs on the project node HIE://, as follows:

The response is formatted like any other Measure API call. The data field contains each of the runs. The response looks as follows:

{
  "data": [
    {
      "formattedValue": "-",
      "letter": null,
      "messages": [],
      "status": "PRESENT",
      "value": [
        {
          "started": "2016-09-12T12:02:59.000+02:00"
        },
        {
          "started": "2016-10-04T15:46:58.000+02:00"
        },
        ...
      ]
    }
  ],
  "dates": [
    "2016-10-04T15:48:18.000+02:00"
  ],
  "metrics": [
    {
      "expression": "Runs",
      "fullName": "runs"
    }
  ],
  "nodes": [{
      "name": "MYPROJECT1",
      "fullPath": "HIE://MYPROJECT1"
    },
    {
      "name": "MYPROJECT2",
      "fullPath": "HIE://MYPROJECT2"
    },
    ...
  ]
}

Each of the objects in the list under "value" has a field "started" that indicates when an analysis was started.

Appendix

Python Example Scripts

This section contains some reference scripts that can be used to interact with the TICS APIs. These scripts require the Requests library to run.

Measure API example

The following script demonstrates how the API can be used to retrieve the TQI and lines of code metrics for all files in a project.

#!/usr/bin/env python
import sys
try:
  import requests
except ImportError:
  print('Please install the requests library')
  sys.exit(1)

# Authentication to use for TICS Viewer
username = 'username'
password = 'mypassword'
auth = requests.auth.HTTPBasicAuth(username, password)

# Specify where the TICS Viewer is located
base_url_parameters = dict(
  host='http://',
  section='',
)
base_url = '{host}/tiobeweb/{section}/api/public/v1/'.format(**base_url_parameters)

# Specify input parameters
input_params = dict(
  filters='Project(),File()',
  metrics='tqi,loc',
)

# Query TICS API
r = requests.get(base_url + 'Measure', auth=auth, params=input_params)
if not r.ok:
  print('An error occurred while querying the TICS API')
  print(r.text)
  sys.exit(1)

# Use the response body
response_body = r.json()
idx = 0
for metric in response_body['metrics']:
  for date in response_body['dates']:
    for node in response_body['nodes']:
      metric_value = response_body['data'][idx]
      print('Value for metric {metric}, node {node} at {date} is {formatted_value}'.format(metric=metric['fullName'], node=node['fullPath'], date=date, formatted_value=metric_value['formattedValue']))
      idx += 1

Annotations API example

The following script demonstrates how the API can be used to retrieve a list of level 1 coding standard violations.

#!/usr/bin/env python
import sys
try:
  import requests
except ImportError:
  print('Please install the requests library')
  sys.exit(1)

# Authentication to use for TICS Viewer
username = 'username'
password = 'mypassword'
auth = requests.auth.HTTPBasicAuth(username, password)

# Specify where the TICS Viewer is located
base_url_parameters = dict(
  host='http://',
  section='',
)
base_url = '{host}/tiobeweb/{section}/api/public/v1/'.format(**base_url_parameters)

# Specify input parameters
input_params = dict(
  filters='Project()',
  metric='Annotations(CS)',
)

# Query TICS API
r = requests.get(base_url + 'Annotations', auth=auth, params=input_params)
if not r.ok:
  print('An error occurred while querying the TICS API')
  print(r.text)
  sys.exit(1)

# Use the response body
response_body = r.json()
title = r.json()['header']['title']
print(title)
violations = r.json()['data']
for violation in violations:
  if not violation['supp']: # if not suppressed
    print('{fullPath}:{line} (Category: {category}, Level: {level}) {msg}'.format(**violation))

List of languages

When referring to a programming language in the API or in the TICS configuration, you should refer to the languages identifier. Below is a list of supported programming languages and their identifiers.