Help documentation

Feeds API

The Go API documented here is a work in progress. Future versions may change this API.

Unless specified otherwise, all the api requests enforce user security. For example, if security is turned on, and a user has access to only two pipelines, all api requests will return data for those two pipelines.

Key

Parameters
Method URL format HTTPVerb Explanation
list http://[server]/go/api/pipelines.xml GET List of all pipelines
list http://[server]/go/api/pipelines/[pipeline_name]/[pipeline_id].xml GET Feed of a pipeline
list http://[server]/go/api/pipelines/[pipeline_name]/stages.xml GET Feed of all stages for the pipeline [pipeline_name]
list http://[server]/go/api/stages/[stage_id].xml GET Xml representation of a stage
list http://[server]/go/pipelines/[pipeline_name]/[pipeline_counter]/[stage_name]/[stage_label].xml GET Xml representation of a stage
list http://[server]/go/api/jobs/[job_id].xml GET Xml representation of a job
  • [pipeline_id] is a unique identifier for a pipeline run.
  • [stage_id] is a unique identifier for a stage run.
  • [job_id] is a unique identifier for a stage run.
  • The urls are case-sensitive.

Examples

  • We use curl, a command line tool for transferring files over HTTP, in the following examples. Of course, you can use any HTTP client library.
  • We assume that the url of the Go server is http://goserver.com:8153/ .
  • We assume security has been switched on, and that there is a user named jez with the password badger .

Given a pipeline configuration like:

<pipeline name="go_pipeline" labeltemplate="go-1.0-${COUNT}">
    <materials>
        <svn url="...."/>
    </materials>
    <stage name="DEV">
        <jobs>
            <job name="UnitTest">
                <tasks>
                <ant target="ut"/>
            </job>
        </jobs>
    </stage>
    <stage name="UATest">
        <jobs>
            <job name="UAT">
                <tasks>
                    <ant target="all-UAT"/>
                </tasks>
            </job>
        </jobs>
    </stage>
</pipeline>

You can get a list of all pipelines using the following command: 

curl -u jez:badger http://goserver.com:8153/go/api/pipelines.xml

This would return xml that looks similar to:

<pipelines>
    <link rel="self" href="http://goserver.com:8153/go/api/pipelines.xml"/>
    <pipeline href="http://goserver.com:8153/go/api/pipelines/go_pipeline/stages.xml"/>
</pipelines>

You can now get a feed of completed stages for go_pipeline using the following command: 

curl -u jez:badger http://goserver.com:8153/go/api/pipelines/go_pipeline/stages.xml

This would return a feed that looks similar to:

<feed xmlns="http://www.w3.org/2005/Atom">
    <title>Stages</title>
    <id>http://goserver.com:8153/go/api/pipelines/go_pipeline/stages.xml</id>
    <author>
        <name>Go</name>
    </author>
    <updated>2009-11-04T19:00:35Z</updated>
    <link rel="self" href="http://goserver.com:8153/go/api/pipelines/go_pipeline/stages.xml"/>
    <link rel="next" href="http://goserver.com:8153/go/api/pipelines/go_pipeline/stages.xml?before=6"/>

    <entry>
        <title>go_pipeline/2/DEV/1</title>
        <updated>2009-11-04T19:00:35Z</updated>

        <id>http://goserver.com:8153/go/pipelines/go_pipeline/2/DEV/1</id>
        <link href="http://localhost:8153/go/api/stages/76.xml" rel="alternate"/>
        <link href="http://localhost:8153/go/pipelines/go_pipeline/2/DEV/1" rel="alternate" type="text/html"/>
        <link href="http://localhost:8153/go/api/pipelines/go_pipeline/55.xml" rel="http://studios.thoughtworks.com/ns/relations/go/pipeline" type="text/xml"/>
        <category scheme="http://studios.thoughtworks.com/ns/categories/go" term="stage" label="Stage" />
        <category scheme="http://studios.thoughtworks.com/ns/categories/go" term="completed" label="Completed" />
        <category scheme="http://studios.thoughtworks.com/ns/categories/go" term="passed" label="Passed" />
    </entry>

    <entry>
        <title>go_pipeline/2/UATest/1</title>
        <updated>2009-11-04T18:54:49Z</updated>
        <id>http://goserver.com:8153/go/pipelines/go_pipeline/2/UATest/1</id>
        <link href="http://localhost:8153/go/api/stages/77.xml" rel="alternate"/>
        <link href="http://localhost:8153/go/pipelines/go_pipeline/2/UATest/1" rel="alternate" type="text/html"/>
        <link href="http://localhost:8153/go/api/pipelines/go_pipeline/55.xml" rel="http://studios.thoughtworks.com/ns/relations/go/pipeline" type="text/xml"/>
        <category scheme="http://studios.thoughtworks.com/ns/categories/go" term="stage" label="Stage" />
        <category scheme="http://studios.thoughtworks.com/ns/categories/go" term="completed" label="Completed" />
        <category scheme="http://studios.thoughtworks.com/ns/categories/go" term="failed" label="Failed" />
    </entry>
</feed>

If you want details of a particular stage, use the alternate link provided in each entry:

curl -u jez:badger http://goserver.com:8153/go/api/stages/76.xml

Note: stage_id in the url above is 76, which matches the first feed entry above.

Additionally, you can directly get the same xml if you know the pipeline name and stage name

For example, in the case above, you could use the following command 

curl -u jez:badger http://goserver.com:8153/go/pipelines/go_pipeline/2/DEV/1.xml

Notice that this is the url one gets by appending .xml to the id element for the stage entry above

The returned xml looks similar to:

<stage name="dev" counter="1">
    <link rel="self" href="http://goserver.com:8153/go/api/stages/65615.xml"/>
    <id>urn:x-go.studios.thoughtworks.com:stage-id:go_pipeline:2:dev:1></id>
    <pipeline name="go_pipeline" counter="2" label="2.1.2322" href="http://goserver.com:8153/go/api/pipelines/go_pipeline/23.xml"/>
    <updated>2010-11-02T17:49:32+05:30</updated>
    <result>Passed</result>
    <state>Completed</state>
    <approvedBy>changes</approvedBy>
    <jobs>
        <job href="http://goserver.com:8153/go/api/jobs/45.xml" />
        <job href="http://goserver.com:8153/go/api/jobs/46.xml" />
    </jobs>
</stage>

You can now get the details of each job in this stage by using the urls in the job elements. For example: 

curl -u jez:badger http://goserver.com:8153/go/api/jobs/45.xml

The returned xml looks similar to:

<job name="build">
    <link rel="self" href="http://goserver.com:8153/go/api/jobs/45.xml"/>
    <id>urn:x-go.studios.thoughtworks.com:job-id:acceptance:1039:twist:1:firefox-7></id>
    <pipeline name="go_pipeline" counter="2" label="2.1.2322" href="http://goserver.com:8153/go/api/pipelines/go_pipeline/23.xml"/>
    <stage name="DEV" counter="1" href="http://goserver.com:8153/go/api/stages/76.xml"/>
    <state>Completed</state>
    <result>Failed</result>
    <properties>
        <property name="cruise_agent">dev-agent</property>
        <property name="cruise_job_duration">1906</property>
        <property name="cruise_job_id">10</property>
        <property name="cruise_job_result">Passed</property>
        <property name="cruise_pipeline_counter">2></property>
        <property name="cruise_pipeline_label">2.1.2322</property>
        <property name="cruise_stage_counter">1</property>
        <property name="cruise_timestamp_01_scheduled">2010-09-22T12:36:15+05:30</property>
        <property name="cruise_timestamp_02_assigned">2010-09-22T12:36:24+05:30</property>
        <property name="cruise_timestamp_03_preparing">2010-09-22T12:36:34+05:30</property>
        <property name="cruise_timestamp_04_building">2010-09-22T12:36:39+05:30</property>
        <property name="cruise_timestamp_05_completing">2010-09-22T13:08:26+05:30</property>
        <property name="cruise_timestamp_06_completed">2010-09-22T13:08:26+05:30</property>
        <property name="tests_failed_count">2></property>
        <property name="tests_ignored_count">0></property>
        <property name="tests_total_count">15></property>
        <property name="tests_total_duration">1599.552></property>
    </properties>
    <agent uuid="2e9c36c1-5a41-43ad-85a7-8195f179388c"/>
    <artifacts baseUri="http://goserver.com:8153/go/files/go_pipeline/2/DEV/1/build" pathFromArtifactRoot="pipelines/go_pipeline/2/DEV/1/build">
        <artifact path="cruise-output/log.xml" type="file"/>
        <artifact path="server/logs/*.log" type="file"/>
        <artifact path="server/config/config" type="file"/>
        <artifact path="server/pipelines/pipelines" type="file"/>
        <artifact path="xml" type="unit"/>
    </artifacts>
    <resources>
        <resource>dev</resource>
        <resource>smoke</resource>
    </resources>
    <environmentvariables>
        <variable name="COMPRESS_JS">No</variable>
        <variable name="COMPRESS_CSS">Yes</variable>
    </environmentvariables>
 </job>