WARNING! THIS PAGE DESCRIBES THE REMOTE API OF AN OLD VERSION OF DC. THE NEW DC (0.5 AND LATER) DOES NOT YET HAVE A REMOTING API.
Introduction
This page contains a description of (the old and discontinued) DamageControl's XML-RPC interface.
Public and Private APIs
Some operations should be open for all. This includes all operations that don't modify any state on the DamageControl system, but merely provide querying functionality. These operations are part of the public API.
Other operations should be restricted to administrators or project developers. These are operations that modify the DamageControls system's state or execute builds on the server.
Public API
Usually unauthenticated. Accessible through for example http://server:4712/public/xmlrpc, on Codehaus these are accessible through http://builds.codehaus.org/public/xmlrpc.
| Syntax | Description |
|---|---|
| string[] status.project_names() | Get all project names registered with the server |
| Build status.current_build(string) | Returns the currently executing build of specified project, takes a project name as a string |
| Build status.last_completed_build(string) | Returns the last completed build of specified project, takes a project name as a string |
| Build[] status.global_search(string) | Searches for the specified phrase in all the projects and returns an array of builds |
Private API
Usually authenticated and encrypted by an Apache proxy. Accessible through http://server:4712/private/xmlrpc. Can be unauthenticated in closed (corporate) environments, on public servers this should definitely be authenticated.
| Syntax | Description |
|---|---|
| string server.trig_build(string project_name, string timestamp) | Requests a build, timestamp has to be formatted according to Timestamp format and must be in UTC, returns a confirmation message from the server. |
Data formats
Build struct
Represents a build result (in the past or currently running)
| XML-RPC type - Field Name | Description |
|---|---|
| string project_name | The name of the project |
| string status | Status of the build, one of "IDLE", "SUCCESSFUL", "FAILED", "QUEUED", "BUILDING", "PAUSED", "CHECKING OUT" |
| Changesets changesets | a Changesets struct containing the modifications in this build |
| string request_time | The time the build was requested, in UTC according to the SCM machine |
| string start_time | The time the build started, in UTC according to the CI machine |
| string end_time | The time the build ended, in UTC according to the CI machine |
| string label | The label of the build, only set for SUCCESSFUL builds |
| string url | URL pointing to a build-specific web page with more detailed info |
Changesets struct
Represents the changesets of one build (a build can contain several changesets).
| XML-RPC type - Field Name | Description |
|---|---|
| Changeset[] changesets | The changesets of this build |
Changeset struct
Represents a set of changes done for the same purposes, some SCMs support this natively (such as Subversion), where they are not supported (as in CVS) DamageControl tries to collate changesets based on message and time.
| XML-RPC type - Field Name | Description |
|---|---|
| Change[] changes | The changes in this changeset |
| string developer | SCM id of the developer |
| string message | The commit message |
Change struct
This struct represents a changed file.
| XML-RPC type - Field Name | Description |
|---|---|
| string path | relative path to the modified file. '/' as path separator |
| string revision | The current revision of the file |
| string time | The timestamp of the file, in UTC according to the SCM, formatted according to the SCM |
| string status | What happened to the file since the last revision, one of: "MODIFIED", "ADDED", "MOVED", "REMOVED" |
Timestamp format
yyyyMMddhhMMss, must always be in UTC.
Why XML-RPC and not <insert favourite rpc technology here>?
- It is platform neutral, and clients can be written for many platforms.
- It is simpler than e.g. SOAP.
- The XML-RPC library for Ruby is excellent!
(We are considering to also support SOAP, but we haven't found an easy and clean way of doing this in Ruby. If you really need SOAP let us know!)