TIOBE TICS 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.

The API follows a RESTful design, meaning that you use the HTTP protocol 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 platform.

HTTP Requests

Data is queried using a 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 "" with branch "", use the following 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&nodes=
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 a 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"
    }
  ],
  "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 two public endpoints available.

Measure API

Use the Measure API to obtain (aggregated) metric values for specific folders or files at a specific date. Use the following URL:

GET 
The input parameters are:
Parameter Value Required Description
metrics metrics yes

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.

nodes paths yes

A list of paths for which you want obtain data. A path identifies a node in the tree representing your archive's hierarchy of folders and source files. For example, use nodes=HIE:////path/to/file.cpp to get data for file.cpp in branch "" in . More information about path literals is found here.

Data is automatically aggregated when a folder path is specified, 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 branches, it is not possible to query data at project level (e.g., nodes=HIE://).

dates date expression no

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.

The date format follows the ISO 8601 standard: YYYY-MM-DDThh:mmTZD, where TZD is the time zone designator (Z for UTC or +hh:mm or -hh:mm). For example, use dates=2013-02-01T00:00Z to get data for February 1, 2013 at midnight in the UTC time zone. It is recommended that you specify the time zone explicitly. If the time zone is omitted, the time is considered local to the server on which the TICS Viewer runs.

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.
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 full path name, e.g. HIE:////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.

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) or a floating point value (e.g. for average cyclomatic complexity).
formattedValue The formatted metric value as a JSON string, using thousands seperators, a limited number of decimals, and a suffix if applicable. Example: 5.12%
letter If applicable, contains the TQI score (A, B, C, D, E, or F), otherwise null.
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.

Path Expressions

The simplest way to provide paths to the nodes parameter of an API method is by using literal expressions. This is fine if you want to know the TQI value for a fixed path in your archive (e.g. HIE://MYPROJECT/trunk), but if you want to retrieve data for paths that you cannot specify up-front (or do not want to), you can use the following expressions and helper functions:

Expression Description
path literal

A path literal is a combination of a hierarchy specifier (HIE or ORG), followed by '://', and then followed by a '/'-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, HIE://MYPROJECT/trunk/path/to/file.cpp denotes file named "file.cpp" in folder "path/to" in branch "trunk", project "MYPROJECT". HIE://MYPROJECT/trunk denotes the root folder in the branch. 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.

Escaping: Because the characters ,, (, and ) have a special purpose in expressions you need to escape them using backslash (\) if they occur in the filename.
a,b,... Returns the union of given paths. Example: HIE://MYPROJECT/trunk,HIE://MYPROJECT/release. The elements can be also be expressions. Example: Children(HIE://MYPROJECT/trunk/folder1),Children(HIE://MYPROJECT/trunk/folder2).
Children(paths) Returns the direct children of one or more input paths. For example, use Children(HIE://MYPROJECT) to obtain the list of branches for MYPROJECT. Because Children accepts a list of paths, you can nest calls. For example, Children(Children(HIE://MYPROJECT)) returns a list of all top-level folders for all branches in MYPROJECT.
Descendants(path) Returns all descendant files and folders that have path as ancestor.
Files(paths) Returns the subset of paths that denote files, leaving out folders, branches, and projects. For example, use Files(Descendants(HIE://MYPROJECT/trunk)) to return all files for branch "trunk".
Folders(paths) Returns the subset of paths that denote folders, leaving out files.

Metric Expressions

In its simplest form a metric expression refers to a single metric, such as loc or tqiFanOut. However, more complex metrics can be obtained using metric generators. A metric generator is a function (named "G") applied to a single metric and one or more modifiers and produces one or more derived metrics that can be used for any API parameter where a list of metrics is expected. For example, in the expression G(loc,Language()) the Language modifier is applied to the loc metric to obtain the Lines of Code per language:

 

The available modifiers are:

Modifier Description
Language(...)

Refines a metric to specific programming language. Programming language needs to be specified using one of the following (upper-case) identifiers: C, CPP (for C++), CS (for C#), HTML, JAVA, JAVASCRIPT, PERL, PHP. For example, to get the lines of code for Java:

 
Level(...)
Category(...)
Rule(...)

Refines a violation metric to a specific coding rule name, category, or level. 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:

 
PerKloc()

Modifies a violation metric to divide its result by lines of code × 1000. For example, to get the number of coding standard violations per thousand lines of code use:

 
Scenario(default)

Modifies tqi metrics to take targets into account that have been entered in the TQI calculator. For example, the metric expressed as G(tqi,Scenario(default)) produces TQI scores that are affected by all targets entered in the TQI calculator. The modifier expects a single parameter: the name of the scenario whose targets should be considered. Currently only one scenario is supported: the scenario named "default".

For example, to get the target TQI score:

 

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 narrow down the scope of the TQI Label as desired. Then, right click the download 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 are:

Parameter Value Required Description
url base64 encoded URL (relative) yes The preferred way to determine this parameter is to follow the steps above.
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).
filename name of file, ending with .png Only when disposition is set The default filename to use by the browser when disposition is attachment. The filename should end in .png.

Authentication

The Web API respects any authentication that you might have configured in your SERVER.txt. If you try to acquire data for a project without providing proper credentials, the server responds with a 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".

How To

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 on the root node HIE://, as follows:

 

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 :

 

Appendix: Metrics

A list of commonly used metric expressions is found below. Expressions for metrics that are not listed here can be found by opening a trend diagram for the desired metric. You will find the expression in the browser window's URL bar.

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
fanOut Average fan out
nrOfFunctions Number of functions
deadCode Dead Code (percentage)
duplicatedCode Duplicated code (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
tqiDeadCode TQI Dead Code
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
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

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

Deprecated pre-7.4 syntax: violations::type=CODINGSTANDARD, violations::type=COMPILERWARNING, violations::type=ABSTRACTINTERPRETATION

G(Violations(CS),Level(1))

Number of coding standard violations for level 1

Deprecated pre-7.4 syntax: violations::type=CODINGSTANDARD\,level=1

G(Violations(CS),Category(Basic))

Number of coding standard violations for category "Basic"

Deprecated pre-7.4 syntax: violations::type=CODINGSTANDARD\,category=Basic

G(Violations(CS),PerKloc())

Number of coding standard violations per 1000 lines of code

Deprecated pre-7.4 syntax: vkloc::type=CODINGSTANDARD

Compliance(CS)

Compliance with respect to coding standard violations (percentage)

Deprecated pre-7.4 syntax: confidence::type=CODINGSTANDARD