CDash:API

Starting in 1.2, CDash is introducing the CDash API with a minimal function. The API is still in beta and the response code might change in the near future. In CDash 1.7 we are adding a more complex API framework.

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

Build API

• Method name: build

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
• 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 are not 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['scheduled'] = returns 1 if the build has been scheduled
  • status['statusid'] = internal status id for further reference

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 (old API)

• 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 (Old API)

• 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