Difference between revisions of "CDash:API"

From KitwarePublic
Jump to: navigation, search
(Get user id)
Line 1: Line 1:
Starting in 1.2, CDash is introducing the CDash API with a minimal function.
+
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.
The API is still in beta and the response code might change in the near future.
+
  
 
= General API =
 
= General API =
 +
This section describes the CDash web API. The CDash REST API is generic and the GET url is usually formatted as follows:
  
The URL should be encoded accordingly to the HTTP 1.1 protocol.
+
  http://mycdashserver/api/?method=method_name&task=task_name&project=project_name
  
= Get build id =
+
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
 +
 
 +
== 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:
 
*URL:
Line 28: Line 129:
 
   /api/getbuildid.php?project=VTK&site=singaporecrisp&stamp=20081013-0109-Experimental&name=Linux-c%2B%2B
 
   /api/getbuildid.php?project=VTK&site=singaporecrisp&stamp=20081013-0109-Experimental&name=Linux-c%2B%2B
  
= Get user id =
+
== Get user id (Old API) ==
  
 
*URL:
 
*URL:

Revision as of 16:53, 30 April 2010

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

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