CDash:API: Difference between revisions
(25 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
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 <tt>View as JSON</tt> is available at the bottom of most of the pages. | |||
[[File:CDash-ViewAsJson-Link.png]] | |||
== 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 <tt>My CDash</tt> page, there is an <tt>Authentication Tokens</tt> section. Enter a description and click on <tt>Generate Token</tt>: | |||
[[File:CDash-AuthenticationToken-Step1.png]] | |||
3) Copy the generated token now as its value will not be available later | |||
[[File:CDash-AuthenticationToken-Step2.png]] | |||
== Available end-points == | |||
[https://github.com/Kitware/CDash/tree/master/public/api/v1 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 = | = General API = | ||
{{ HistoricalCDash }} | |||
This section describes the CDash web API. The CDash REST API is generic and the GET url is usually formatted as follows: | This section describes the CDash web API. The CDash REST API is generic and the GET url is usually formatted as follows: | ||
Line 21: | Line 65: | ||
** array[]['name'] = project name | ** 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 == | == Build API == | ||
* Method name: build | * 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 === | === Defects === | ||
Line 74: | Line 155: | ||
=== Schedule a build (build management) === | === Schedule a build (build management) === | ||
* Task name: schedule | * 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. | * Description: returns an array with the current status of the schedule. | ||
http://mycdashserver/api/?method=build&task=schedule&project=MyProject | 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 | * Return an array containing the status of the scheduling | ||
** status['scheduled'] = returns 1 if the build has been scheduled | ** status['scheduled'] = returns 1 if the build has been scheduled | ||
** status[' | ** 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 == | == Coverage API == | ||
Line 119: | Line 234: | ||
** array[username]['neutralfiles'] = number of commits that didn't fix or break the dashboard | ** array[username]['neutralfiles'] = number of commits that didn't fix or break the dashboard | ||
== Get build id | == Get build id == | ||
*URL: | *URL: | ||
Line 141: | Line 256: | ||
/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 == | ||
*URL: | *URL: |
Latest revision as of 03:07, 21 October 2018
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 is currently out-of-date and may contain errors but is retained for historical reference. Additional guidance can be found via the mailing list. |
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