CDash:API

The API is still in beta and the response code might change in the near future.

JSON data representation

We are gradually converting CDash's frontend from XSLT to AngularJS. For any page that has already been converted, you can now directly access the underlying data in JSON format.

Starting with CDash 2.5.0, a link View as JSON is available at the bottom of most of the pages.

Authentication Token

An authentication token allows to use API endpoint requiring elevated access.

Step by step:

1) Login from the web interface entering your email and password

2) At the bottom of My CDash page, there is an Authentication Tokens section. Enter a description and click on Generate Token:

3) Copy the generated token now as its value will not be available later

Available end-points

Go here to see an up-to-date list of all the pages that have been converted to AngularJS so far.

Examples

For example,

https://open.cdash.org/api/v1/index.php?project=VTK

returns a JSON representation of the data that used to render

https://open.cdash.org/index.php?project=VTK .

General API

This section describes the CDash web API. The CDash REST API is generic and the GET url is usually formatted as follows:

 http://mycdashserver/api/?method=method_name&task=task_name&project=project_name

The URL should be encoded accordingly to the HTTP 1.1 protocol and by default the result is returned as a JSON array.

Project API

• Method name: project

List

• Task name: list
• Description: Returns a list of projects id and names

 http://mycdashserver/api/?method=project&task=list
 

• Return an array of projects:
  • array[]['id'] = project id
  • array[]['name'] = project name

Login

• Task name: login
• Project name (mandatory) - The name of the project whose web API key you are using.
• Key (mandatory - POST) - The 40-character web API key displayed on the Miscellaneous tab of the Edit Project page. Pass as a POST field for security.
• Description: A project admin can use the project's web API key to obtain a temporary token that will allow them to call protected web API methods.

 http://mycdashserver/api/?method=project&task=login&project=MyProject
 (You must pass key=<api key> as a POST parameter)

• Return a status message and the token that was created
  • array['status'] = true or false depending on whether the token was successfully created
  • array['token'] = the 40-character temporary API token that you can use in subsequent web API calls

Build API

• Method name: build

Revision Status

• Task name: revisionstatus
• Project name: mandatory
• Revision: mandatory: GIT hash or SVN revision
• Description: Returns an array of build defects

 http://mycdashserver/api/?method=build&task=revisionstatus&project=test&revision=abcde
 

• Return an array of builds: array(build);
  • $build['id'] = internal id of the build
  • $build['name'] = name of the build as specified by CTest
  • $build['os'] = name of the OS
  • $build['starttime'] = start time of the build
  • $build['endtime'] = end time of the build
  • $build['submittime'] = submission time of the build
  • $build['configureerrors'] = number of configuration errors
  • $build['configurewarnings'] = number of configuration warnings
  • $build['loctested'] = number of lines of code tested (if build is associated with coverage)
  • $build['locuntested'] = number of lines of code untested (if build is associated with coverage)
  • $build['builderrors'] = number of build errors
  • $build['buildwarnings'] = number of build warnings
  • $build['testnotrun'] = number of tests not run
  • $build['testpassed'] = number of tests passed
  • $build['testfailed'] = number of tests failed

Defects

• Task name: defects
• Project name: mandatory
• Description: Returns an array of build defects over time (currently limited to the 1000 last entries)

 http://mycdashserver/api/?method=build&task=defects&project=MyProject
 

• Return an array of builds: array(build);
  • build['month'] = month of the build
  • build['day'] = day of the build
  • build['year'] = year of the build
  • build['time'] = time of the build
  • build['builderrors'] = number of build errors
  • build['buildwarnings'] = number of build warnings
  • build['testnotrun'] = number of tests not run
  • build['testfailed'] = number of tests failed

Checkins/Defects

• Task name: checkinsdefects
• Project name: mandatory
• Description: Returns an array of build defects and number of updated files for the build
• Currently limited to the last 1000 builds for the project

 http://mycdashserver/api/?method=build&task=checkinsdefects&project=MyProject
 

• Return an array of builds: array(build);
  • build['nfiles'] = number of updated files
  • build['builderrors'] = number of build errors
  • build['buildwarnings'] = number of build warnings
  • build['testnotrun'] = number of tests not run
  • build['testfailed'] = number of tests failed

Site/Test Failures

• Task name: sitetestfailures
• Project name: mandatory
• Group: optional: Nightly, Continuous, Experimental
• Description: returns an array of sites and corresponding names of the failing tests.

 http://mycdashserver/api/?method=build&task=sitetestfailures&project=MyProject&group=Nightly
 

• Return an array of sites with the index being the id of the build
  • site['name'] = name of the machine
  • site['buildname'] = name of the build
  • site['cpu'] = processor speed
  • site['memory'] = physical memory
  • site['tests'] = name of the tests

Schedule a build (build management)

• Task name: schedule
• token (mandatory - POST) - The token obtained from the project API's login method. Pass as a POST parameter for security.
• project (mandatory) - Name of the project
• repository (mandatory) - Name of the repository
• userid (optional) - User scheduling the build (default is administrator)
• type (option) - Experimental, nighty, continuous (Experimental=0,Nightly=1,Continuous=2)
• module (optional) - Name of the repository module
• tag (optional) - Name of the repository tag
• suffix (optional) - Suffix for the build
• configuration (optional) - Configuration type for compilation (Debug=0,Release=1,RelWithDebInfo=2,MinSizeRel=3)
• cmakeversion (optional) - Version of CMake to use
• siteid (optional) - Specify that the build should run on this site
• osname (optional) - Name of the OS to run the build
• osversion (optional) - Version of the OS to run the build
• osbits (optional) - Number of bits of the target OS
• compilername (optional) - Target compiler
• compilerversion (optional) - Target compiler version
• libraryname (optional) - Library name (currently only one can be specified)
• libraryversion (optional) - Library version

• If none of the optional parameters is set, CDash will try to schedule the build on any available machines.
• Description: returns an array with the current status of the schedule.

 http://mycdashserver/api/?method=build&task=schedule&project=MyProject
 

• Return an array containing the status of the scheduling
  • status['status'] = true or false depending on whether the schedule was successfully submitted
  • status['scheduled'] = 1 if the build has been scheduled
  • status['scheduleid'] = internal schedule id for further reference

Get status of a scheduled build (build management)

• Task name: schedulestatus
• project (mandatory) - Name of the project
• scheduleid (mandatory) - Id of the schedule
• Description: returns an array with the current status of the schedule.

 http://mycdashserver/api/?method=build&task=schedulestatus&project=MyProject&scheduleid=12
 

• Return an array containing the status of the scheduling
  • status['scheduled'] = returns 1 if the build has been scheduled
  • status['status'] = status code (-1:not found,0:scheduled,2:running,3:finished,4:aborted,5:failed)
  • status['statusstring'] = status string
  • status['scheduleid'] = id of the schedule
  • status['builds'] = array of build id's that were performed as a result of this scheduled job

Coverage API

• Method name: coverage

Coverage per directory

• Task name: directory
• Project name: mandatory
• Description: Return the number of lines untested per directory

 http://mycdashserver/api/?method=coverage&task=directory&project=MyProject

• Returns an array of LOC tested and untested
  • array[directory_fullpath]['loctested'] = # loc tested
  • array[directory_fullpath]['locuntested'] = # loc untested

User API

• Method name: user

Defects per user

• Task name: defects
• Project name: mandatory
• Description: Return the commit statistics per user

 http://mycdashserver/api/?method=user&task=defects&project=MyProject

• Returns an array of users
  • array[username]['builderrors'] = number of errors and warning caused by the user
  • array[username]['builderrorsfiles'] = number of commits causing either a fix or failure of errors and warnings
  • array[username]['buildfixes'] = number of fixes (warnings or errors) done by the user
  • array[username]['buildfixesfiles'] = number of commits causing either a fix or failure of errors and warnings
  • array[username]['testerrors'] = number of test failing caused by the user
  • array[username]['testerrorsfiles'] = number of files committed that produced a test failure
  • array[username]['testfixes'] = number of test fixed by the user
  • array[username]['testfixesfiles'] = number of files committed that fixed a test
  • array[username]['neutralfiles'] = number of commits that didn't fix or break the dashboard

Get build id

• URL:

 /api/getbuildid.php?

• Parameters:
  • project: name of the project
  • site: name of the site
  • siteid: override the site name if siteid is provided (optional)
  • stamp: time stamp of the build
  • name: build name

• Returns:

• • <buildid>buildid</buildid>
  • <buildid>not found</buildid> if no buildid found

• Example:

 /api/getbuildid.php?project=VTK&site=singaporecrisp&stamp=20081013-0109-Experimental&name=Linux-c%2B%2B

Get user id

• URL:

 /api/getuserid.php?

• Parameters:
  • project: name of the project
  • author: name of the cvsuser/svnuser

• Returns:

• • <userid>userid</userid>
  • <userid>not found</userid> if no user found

• Example:

 /api/getuserid.php?project=VTK&cvsuser=test