Query Web API

webapi

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.
URLs should be encoded using percent encoding (%20 for spaces, %2B for +, etc).

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"
  ]
}
"Data", "metrics", "nodes", etc. are JSON object fields. The response is guaranteed to contain at least these fields, but might contain more when we add functionality to the API later. As such, you should not attempt to interpret the response by assuming the value you need is on a certain line or column number, or by using regular expressions! You should also not assume that the fields of the JSON object are in a specific order. You should only interpret the response by running it through a JSON parser and accessing the documented fields of the resulting JSON object. We recommend using a standard library for JSON parsing, such as Gson for Java, or the json library in Python.

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:

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:

Parameter Value Description
metrics

(required)

metric expression

A list of metrics for which you want to obtain data. For example, use metrics=tqi to obtain the metric values for the TIOBE Quality Indicator or metrics=loc,eloc to get the metric values for both the Lines of Code and Effective Lines of Code metrics.

A list of commonly used metrics can be found here. Unrecognized identifiers will be silently ignored: the response will not contain any data for it and no error will be generated.

filters

(optional)

filter expression
  • Since version: 8.4

The filters to apply when retrieving data. For example, use filters=Project(foo),Sub(src),Sub(main) to keep only measurements from subsystem src/main in project foo. To query data on a specific date, use the Date(…) filter. More information about filter expressions is found here.

Measurements are aggregated using the metric's intrinsic aggregation function. You cannot control the aggregation function via the API. As it does usually not make sense to aggregate data over different branches from the same project, the API takes only measurements from the "default" branch when no branch is specified.

This parameter is optional; when you omit it (and do not use the deprecated nodes parameter), the most current data from all projects is aggregated into one metric value.

nodes (or paths)

(optional)

path expression
Deprecated Please use the more powerful filters parameter instead. Although this parameter is deprecated, it will remain supported for backwards compatibility. Please refer to the path expression

When you provide a path that does not exist, the output data array will contain an element having value: null and status: "NONEXISTENT".

dates

(optional)

date expression
Deprecated Please use the Date or Run filter in the filters parameter instead. Although this parameter is deprecated, it will remain supported for backwards compatibility.

One or more dates for which you want to obtain data. If omitted, the last TICS measurement date (for the respective project) is used. The requested date does not need to coincide with a measurement date. In that case, the metric value for the immediately preceding measurement date will be returned.

wait

(optional)

true or false

(default=true)

  • Since version: 2020.1

Whether the API should await cache generation for any project in the queried scope.

callback

(optional)

function name
  • Since version: 8.4

Use when you want to call the API using the JSONP technique.

The JSON output fields are:

Field Description
metrics

An array of metric objects for which data is available in the data field. These objects have the following fields:

NameValue
expression The unique identifier for this metric. Example: loc.
fullName The human-readable name for this metric, as it is displayed in the viewer. Example: Lines of Code.
projectGroup An JSON object containing a field named elements that is an array of nested project groups pertaining to this metric value. This field is only present when a project group filter is used.
nodes

An array of path objects for which data is available in the data field.

A path object denotes a node in a particular view on the source tree and has the following fields:

NameValue
name The simple name of the path, e.g. file.cpp
fullPath The path literal, e.g. HIE://project/branch/path/to/file.cpp
Limitation: You cannot query data for paths referring to multiple projects. You need to split the API call up so that each call refers to only one project.
dates

An array of stringified timestamps for which data is available in the data field, in ISO 8601 format. The time zone used is that of the viewer's machine. Example: 2014-02-07T16:19:09.000+01:00. If the optional "dates" input parameter was omitted, this array contains a single item: the timestamp of the last TICS run for the respective project. The order of the dates is in ascending chronological order, except if an explicit list of dates is given in the dates input parameter, in which case the output dates are provided in the same order as the input.

data

An array containing the requested metric value objects. These objects have the following fields:

NameValue
value The unformatted metric value as a JSON number. Depending on the metric, this will be an integer (e.g., for lines of code), a floating point value (e.g., for average cyclomatic complexity) or a list of objects (e.g., for runs).
status String value indicating the metric value status. Normally the status is PRESENT indicating that a metric value could be computed for the given input parameters. However, when the metric value could not be computed, it can have one of the following statuses:
  • ERROR: indicates one or more TICS analysis errors for the provided path and metric.
  • NONEXISTENT: indicates that the provided directory or file does not exist (or no longer exists).
  • DISABLED: indicates that the provided metric is not enabled in the database.
  • NODATA: indicates that there is no data in the database for provided path and metric, for instance because the file has not been analyzed yet.
  • There are other unspecified statuses which you should not rely upon.
letter If applicable, contains the TQI score (A, B, C, D, E, or F), otherwise null.
formattedValue The formatted metric value is a string representation of the metric value. It uses the same formatting as the viewer and can therefore change between versions. It can contain HTML, for instance for delta metrics or when the metric value could not be determined due to analysis errors. Therefore, do not attempt to interpret the value or do computations with it. Use the value for that instead.
The data array contains a metric value object per metric, date, and node combination, and thus contains |metrics| × |dates| × |nodes| elements. Pseudo-code for iterating over the data array:
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;
    }
  }
}
Note that you should iterate over the actual objects present in the metrics, dates, and nodes fields of the response, and not over the input parameters.

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 
Warning: Depending on the number of annotations, the query can become slow and the response might become large. Consider adding filters such as a Language filter to prevent this; see below.

The input parameters of the Annotations API are:

Parameter Value Description
metric

(required)

One of Annotations(CS), Annotations(CW), Annotations(AI), Annotations(SEC), Annotations(DUP), Annotations(COMPLEXITY), Annotations(DEADCODE), Annotations(DUPCUST)

Specifies whether to retrieve annotations for Coding Standards (CS), Compiler Warnings (CW), Abstract Interpretation (AI), Security Violations (SEC).

Since version 2020.1, you can also retrieve information about Code Duplication (DUP), Complexity (COMPLEXITY), Dead Code (DEADCODE), and Custom Code Duplication (DUPCUST)

filters

(required)

filter expression

Specifies the filters that should be applied. All filters are optional except for the Project filter. The following filters are supported:

  • Project(…): only return annotations for this project.
  • Language(…): only return annotations for this language. The language should be specified using one of the built-in language identifiers.
  • Level(…), Category(…), Rule(…), Ruleset(…): only return annotations for given level, category, rule, or ruleset.
  • Suppressions(…): whether suppressed violations should be included. Suppressed violations are omitted by default. Specify Suppressions(yes) to only get suppressed violations. Specify Suppressions(either) to get both suppressed and unsuppressed violations.
  • View(…): whether to retrieve annotations for the Hierarchical (View(HIE)), Organizational (View(ORG)), or Rational Rose (View(RR)) view (where configured). If omitted, the Hierarchical view is used.
  • Sub(…): only return annotations for the given subsystem. You can specify multiple Sub filters to specify a nested subsystem. For example, to get all annotations for the component comp in module mod in the organizational view of project X, you would use: Project(X),View(ORG),Sub(mod),Sub(comp).
  • IsNew(yes): only return annotations that are new. When you provide this filter, you also need to provide a DeltaDate(...) filter preceding the IsNew filter to indicate the delta reference date. The DeltaDate filter requires a date expression as parameter. For instance, to get annotations that are new with respect to the previous run, you use the following two filters: DeltaDate(Run(-2)),IsNew(yes). Note that this filter is only supported for annotation types that support history, i.e. the violation-based metrics.

In general, the order in which you specify the filters is not important, however there are some exceptions: the Project filter should precede any Sub filters, and the IsNew filter should be preceded by the DeltaDate filter.


  • Since version: 2020.1

When requesting annotations for code duplication, the optional filter DupScope(type) is also supported. This filter is used to return only annotations that are either internal or external with respect to a certain scope. Type should be any of:

fileInternal Only return duplications that are local (internal) to a file.
fileExternal Only return duplications that are not local (external) to a file.
scopeInternal Only return duplications that are local (internal) to the given scope.
scopeExternal Only return duplications that are not local (external) to the given scope.

In case of the last two types, the scope is determined by the filter that precede the DupScope filter. For instance, to get all duplications inside foo/bar for project X that are external to foo, use: filters=Project(X),Sub(foo),DupScope(scopeExternal),Sub(bar)

wait

(optional)

true or false

(default=true)

  • Since version: 2020.1

Whether the API should await cache generation for any project in the queried scope.

callback

(optional)

function name
  • Since version: 2020.1

Use when you want to call the API using the JSONP technique.

The JSON output fields are:

Field Description
header

A JSON object containing meta-data about the response. Currently, it only contains a title field:

NameTypeValue
title string Comprehensive title describing which annotations are in the response. Do not rely on the specific contents of this string, as it might change in the future!
data

An array of Annotation objects that pass the given filters, in no particular order. The returned fields depend on the type of annotations requested.

Each object contains the following common fields:

NameTypeValue
fullPath string The path literal denoting the file where the violation occurs, e.g. HIE://project/branch/path/to/file.cpp
line integer The line number on which the issue or fact occurs. In case of a fact that spans multiple lines, such as for code duplication, this fields indicates the start of the range.
type string The type of this annotation. Can be CS, AI, COMPLEXITY, etc.

When requesting violation-based annotations, each object additionally contains the following fields:

NameTypeValue
level integer The violation's level
category string The violation's category name
rule string The violation's rule name
msg string The message of the annotation
supp boolean Whether the violation is suppressed by the violation suppression mechanism or not. By default, only unsuppressed violations will be shown unless you specify a Suppression(…) filter (see above).
count integer The number of violations that this annotation represents. This is usually 1. However, it sometimes happens that a code checker produces multiple violations with the exact same line number, rule, and message. This might happen for instance when there is a violation on a line produced by a C++ macro expansion.
buildTargets array of string
(optional)
The build targets for which this violation holds. This field is omitted when the violation concerns all configured targets.

When requesting code duplication annotations, each object contains the following fields in addition to the common ones:

NameTypeValue
endLine integer The line number on which the duplication ends
duplicatedWith object Object containing fullPath, line, endLine fields that describe the other side of the duplication

When requesting complexity annotations, each object reports the complexity of one function found in the source code:

NameTypeValue
complexity integer The complexity of the function. Note that the decision count can be obtained by subtracting 1 from the complexity.
functionName string The name of the function

When requesting dead code annotations, each object contains the following fields in addition to the common ones:

NameTypeValue
endLine integer The line number on which the duplication ends

Examples

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:

Parameter Value Description
project

(required)

text The name of the project you want to get the status for.
branch

(optional)

text The name of the branch inside the project that you want to get the status for. If omitted, the default branch for the project is chosen.
date

(optional)

date expression The date for which you want to get the quality gate status. If omitted, the status for the latest run is returned.
fields

(optional)

array of strings
Since version 2022.1

Comma-separated lists of field names that should be returned in the output. The purpose of this field is to prevent over-fetching: you should only specify the fields that are you are going to use. Valid options are: details and annotationsApiV1Links. See below in the output field description what these fields entail. Leave empty to get all basic output, without these fields.

The JSON output fields are:

Field Description
passed

Boolean value indicating whether this project (and branch) passes all quality gates configured for it. If no quality gates are configured for the project (or all are disabled), field will be 'true'.

url

URL that opens the TiCS Viewer and shows the results of the quality gate status. The URL is relative to the viewer's base URL, which is of the form http:/host:port/tiobeweb/section. The URL will contain a Date filter so that it is bound to the requested date.

message

String that states the overall quality gate status, for example: Project failed to pass 2 of 3 quality gates. Does not contain HTML entities.

gates

An array of Quality Gate objects. Array does not contain elements for disabled quality gates. Each Quality Gate object contains the following fields:

NameTypeValue
passed boolean Boolean value indicating whether this project (or branch) passes this quality gate associated with.
name string Name of the quality gate.
conditions array Array of Condition objects.

Each Condition object contains the following fields:

NameTypeValue
passed boolean Boolean value indicating whether this project (or branch) passes this condition.
error boolean Boolean value indicating whether the condition did not pass because of an evaluation error. An example of an evaluation error is that the reference date could not be resolved, for instance because the referenced baseline no longer exists.
message string Statement indicating the condition and why it passed or failed, example or a failed condition: Coding Standard Violations for levels 1, 2, 3 should be equal to 0, but actual value is 114.
details Details object
Since version 2022.1
Contains details about the failing condition. This field is only present when you specified fields=details as input parameter. This fields will be null, when the gate condition is not defined 'for each file' (i.e. it is defined for the whole project). See below for details about the Details object.

A Details object contains (actionable) details about the problem(s) that make the condition fail. The details are returned in a format that allows the API to be extended later to return extra data, without breaking clients. The object has the following fields:

NameTypeValue
itemTypes array of ItemType The item types that are output for this condition. Can currently only contain file, however it is anticipated that in the future the API can also return item type issue.
items array of Item objects Each element in the array represents an actionable item that causes the condition to fail. The number of elements in this array is limited to a (hard-coded) limit as denoted by the field itemLimit.
dataKeys map of DataKey objects Describes the keys that occurs in the items.data map. For file item types, the map is guaranteed to contain the key actualValue, which describes the actual value for the metric on which the failing condition is defined.
itemLimit integer The maximum number of items returned by this API.
itemCount integer The total number of items that would have been returned if it wasn't for the row limit.

A DataKey object contains more information about the keys that appear in the item.data map:

NameTypeValue
title string Title that describe this particular data key. Example: 'Δ Delta Coding Standard Violations'.
order natural number Suggested display order for the data keys.
itemType ItemType The type to which this key pertains, which is one of the types specified in output field itemTypes.

An Item object contains information about one actionable item:

NameTypeValue
name string The name of the item, which is the full filename in case of item type file.
link string URL that shows more information about the item in the viewer. For instance, the URL might point to the Annotated Source showing the introduced issues for the particular file and metric. The URL is relative to the viewer's base URL.
itemType string The type of the item, which is one of the types specified in output field itemTypes.
data map of ItemData objects Map from keys to ItemData objects, which provide the metric values. For file item types, the map is guaranteed to contain the key actualValue, which describes the actual value for the metric on which the failing condition is defined.

An ItemData object containing information about the relevant metric value(s) in the quality gate condition evaluation:

NameTypeValue
value string Numerical metric value. Example: 12.34.
formattedValue string Formatted metric value. Examples: +5, 12.34%.
classes array of strings Classes that characterize this value. Possible values:
  • delta-worse, delta-better: Value is a delta metric value representing a quality degradation/improvement.
  • delta-increased, delta-decreased: Value is a delta metric value representing an increase/decrease. These classes are used for metrics that do not define whether higher values are better or worse.
annotationsApiV1Links

An array of objects containing a field url that points to the Annotations API that you can use to retrieve the particular annotations that are relevant for the failing conditions in the quality gates. A failing condition will result in a URL in the array if the request will produce a useful result. For instance, if the quality gate condition is relative, i.e. makes use of a delta metric, a URL will only be output when annotations support history.

Currently, if no quality gates are defined for the project, the array will contain a URL for each (enabled) violation-based metric, and with filters that ensure that only violations that are new with respect to the previous run are returned. This might change in the future.

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:

Parameter Value Required Description
url base64 encoded URL (relative) yes The easiest way to determine this parameter is to follow the steps above. You can also generate it programmatically by base64 encoding the following (relative) URL: TqiLabel.html#axes=Project(MYPROJECT)&print=true, where MYPROJECT should be replaced by the project name that you want to generate the label for.
disposition attachment or inline No (default=inline) The disposition type used by the HTTP response. Use the value attachment to indicate that the browser should prompt the user to save the response locally. Use the value inline to have the browser process the response normally (as per its media type), which can be used to embed the image in your dashboard (e.g. using an IFRAME).
filename name of file, ending with .png Only when disposition is set to attachment The default filename to be used by the browser when disposition is attachment. The filename should end in .png.
zoom The zoom factor No (default=1)

Use this to generate a higher-resolution image (up to 4 times).

There is a known issue with the third-party wkHtmlToImage tool that is used to generate the image, where the zoom functionality is not working on Ubuntu 20.04. If you are encountering this issue, you can specify the zoom query parameter as part of the base64-encoded url parameter instead (available in version 2022.2.1 and higher).

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

Expression Description
loc Lines of code
eloc Effective lines of Code
gloc Lines of code including generate code
cycloxAverage Average cyclomatic complexity
cycloxMax Maximum cyclomatic complexity
cycloxTotal Total cyclomatic complexity
nrOfDecisionPoints The decision count (complexity - 1)
fanOut Average fan out
nrOfFunctions Number of functions
deadCode Dead Code (percentage)
duplicatedCode Code Duplication (percentage)
tqi TIOBE Quality Indicator
tqiTestCoverage TQI Code Coverage
tqiAbstrInt TQI Abstract Interpretation
tqiComplexity TQI Cyclomatic Complexity
tqiCompWarn TQI Compiler Warnings
tqiCodingStd TQI Coding Standards
tqiDupCode TQI Code Duplication
tqiFanOut TQI Fan Out
tqiSecurity TQI Security. Available for projects using TQI version 4.0 or higher.
tqiDeadCode TQI Dead Code. Available only for projects using TQI version 3.11 and lower.
linesAdded, linesDeleted, linesChanged Sum of lines added, deleted, or changed in this run
changerate Change rate (total of lines added, deleted, and changed)
accuChangerate Accumulative change rate over all runs
runs List of runs, i.e., timestamps of moments when an analysis was performed
scope+TestCoverage+type
where scope is one of unit, system, integration, or total
and type is one of Branches, Statements, Functions, or Decisions
Unit, System, Integration, or Total Code coverage for Branches, Statements, Functions, or Decisions (16 possible combinations)
Violations(+type+) where type is one of CS,CW,AI, SEC

Total number of coding standard violations, compiler warnings, abstract interpretation violations, or security violations

PerKloc(Violations(CS))

Number of coding standard violations per 1000 lines of code

Log(loc,2)

The logarithm (base 2) of the Lines of Code metric.

Compliance(CS)

Compliance with respect to coding standard violations (percentage)

Delta(+metric+) where metric is one of the other metrics in this table
The difference between the current value for a metric and the value at the time of the previous baseline. If no baseline is set, the value from a month ago is used instead.
Delta(+metric+,+date+) where metric is one of the other metrics in this table and date is the date to compare to
The difference between the current value for a metric and the value at the date specified. The date should be specified as a date expression.

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.

Escaping: Because the characters ,, (, and ) have a special purpose in expressions you need to escape them using a backslash if they occur in a parameter name (which you should encode as %5C in the URL).
Filter Description
Project(…)

Confines metric values to the given project(s). For example, to get the Lines of Code (loc) for a specific project:

 

To get the Lines of Code per project use:

 

Branch(…)

Confines metric values to the given branch. Should always be preceded by a Project filter. For example, to get the Lines of Code (loc) for a specific branch:

 
ProjectGroup(…)

Confines metric values to the given project group(s). For example, to get the Lines of Code per project group:

 

The projectGroup fields in the JSON output will contain the encountered project groups. To specify nested project groups, use multiple expressions: ProjectGroup(foo),ProjectGroup(bar).

Limitation: The Measure API will not give proper results for projects that are not inside a project group.
Sub(…)

Confines metric values to the given subsystem. Nested subsystems can be specified by using multiple expressions. When specifying a subsystem, you should also specify a Project filter. For example, to get the Lines of Code for a specific subsystem src/main/java in project foo in the Hierarchical view, use:

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

When specifying a subsystem in another view that the hierarchical view, you need to specify a View filter. For instance, to get the Lines of Code for Team 2 as specified in the Organizational View, use:

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

Confines metric values to given File. For example, to get the Lines of Code (loc) for all files in a project:

 
View(…)

This filter is needed when you use the Sub filter, and want to query subsystems from the Organizational (View(ORG)) or Rational Rose (View(RR)) view. When querying the Hierarchical view, the View(HIE) filter can be left out because it is implicit.

Language(…)

Confines metric values to the given programming language(s). Programming languages need to be specified using one of the built-in programming language identifiers. For example, to get the lines of code for Java:

 
Level(…)
Category(…)
Rule(…)
Ruleset(…)

Confines violation metrics to a specific coding rule level, category, name, or ruleset. For example, to get the coding standard violations for level 1 use:

 

Provide a comma-separated list of rule property values to create multiple metrics. For example, to get the coding standard violations for categories Basic and Design use:

 

Omit the parameter to split by all available property values. For example, to create a metric for each available rule:

 
Date(date expression)

The date for which to obtain data. If omitted, the last TICS measurement date (for the respective project(s)) is used. The requested date does not need to coincide with a measurement date. In that case, the metric value for the immediately preceding measurement date will be returned.

For example, to get the value for Lines of Code at January 2, 2019, use:

 

CodeType(…)
Since version 9.1

Confines metric values to the given code types. A code type of a file is either production, external, or test. When you do you not specify a CodeType filter, the filter CodeType(production) is implicitly used. To get all code for a project, including test and external code, use:

 

Information about configuring code types is found here

Run()
Run(Period(begin date))
Run(Period(begin, end))
Since version 2019.4

The runs for which to obtain data. When using this filter, you should not use the Date() filter.

Use Run() without any parameters to query data for all runs. For older projects that have many runs, this can be very expensive. Please restrict the number of runs that will be returned by specifying a period. Typically, you only want to specify the period's begin date. For example, to get the Lines of Code measurements for all runs since January 2, 2019 or later use:

 

To get the Lines of Code measurements for a sliding window of the last three months use:

 

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:

Expression Description
date literal A date literal of one of the following types:
  • In the ISO 8601 format: YYYY-MM-DDThh:mmTZD, where TZD is the time zone designator (Z for UTC or +hh:mm or -hh:mm). For example, use 2013-02-01T00:00Z to get data for February 1, 2013 at midnight in the UTC time zone. You can leave out trailing time and date elements as desired. For example, use 2013-02 to specify February 1, 2013 at midnight in the UTC time zone. If the time zone is omitted, the time is considered local to the server on which the TICS Viewer runs.
  • In UNIX Epoch time format, which is the number of seconds that have elapsed since January 1, 1970 at 00:00 in the UTC time zone. For instance, specify 1359676800 for February 1, 2013 at midnight in the UTC time zone.
Run(index)

Resolves to the date associated with the run (analysis) found at the given index in the complete list of runs sorted in ascending order for all projects in the current scope. A negative index can be used to access the list in descending order, which is useful to get to the most recent runs. Most useful expressions are:

  • Run(-1): The last run
  • Run(-2): The second-to-last run
  • Run(0): The first run

When you combine a Run date expression (with negative index) with a Date(...) filter, the last run will be interpreted as the run pointed to by the Date filter.

RunChange(index)

Similar to Run(), but the list that is indexed only contains runs having changes, which are files that have been added or changed, but not deleted. Only negative indices are allowed. The most useful expressions are:

  • RunChange(-1): The last run with changes
  • RunChange(-2): The second-to-last run with changes
Baseline(name) Resolves to the date associated with the baseline with the given name in the current scope is defined.
default Resolves to the default reference date, which is the date associated with the last baseline in the current scope, or the last month if no baseline defined in the current scope.
Add(date expression,duration) Computes a date by adding given duration to the date pointed to by given date expression. Durations should be in ISO Duration format. For instance, Add(Run(-1),P-7D) would resolve to 7 days before the last analysis.
duration You can also directly specify a duration in ISO Duration format at all places where a date expression is expected. The duration will be interpreted relatively to the last analysis date (Run(-1)). For instance, Delta(loc,P-7D) is a shorthand for writing Delta(loc,Add(Run(-1),P-7D)).

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.

Deprecated The use of path expressions in input parameters is deprecated. Please use the more powerful filters parameter instead (when available).

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.

Timeouts Make sure that you account for the cache generation duration by appropriate configuration of timeout settings in your HTTP library and proxy server.

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.

Programming Language Identifier
C C
C++ CPP
C# CS
Dart DART
Go GO
Java JAVA
JavaScript JAVASCRIPT
Kotlin KOTLIN
Lua LUA
Matlab MATLAB
Objective-C OBJECTIVEC
PL/SQL SQL
Python PYTHON
Scala SCALA
Swift SWIFT
TypeScript TYPESCRIPT
Visual Basic .NET VB
XAML (WPF) XAML