CDash:API

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

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) - The 40-character web API key displayed on the Miscellaneous tab of the Edit Project page.
• 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&key=<api key>

• 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

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) - The token obtained from the project API's login method
• 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

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 (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