Difference between revisions of "CDash:API"

From KitwarePublic
Jump to navigationJump to search
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