335 lines
7.1 KiB
XML
335 lines
7.1 KiB
XML
<chapter xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xml:id="chap-api">
|
|
|
|
<title>Using the external API</title>
|
|
|
|
<para>
|
|
To be able to create integrations with other services, Hydra exposes
|
|
an external API that you can manage projects with.
|
|
</para>
|
|
|
|
<para>
|
|
The API is accessed over HTTP(s) where all data is sent and received
|
|
as JSON.
|
|
</para>
|
|
|
|
<para>
|
|
Creating resources requires the caller to be authenticated, while
|
|
retrieving resources does not.
|
|
</para>
|
|
|
|
<para>
|
|
The API does not have a separate URL structure for it's endpoints.
|
|
Instead you request the pages of the web interface as
|
|
<literal>application/json</literal> to use the API.
|
|
</para>
|
|
|
|
<section>
|
|
<title>List projects</title>
|
|
|
|
<para>
|
|
To list all the <literal>projects</literal> of the Hydra install:
|
|
</para>
|
|
|
|
<programlisting>
|
|
GET /
|
|
Accept: application/json
|
|
</programlisting>
|
|
|
|
<para>
|
|
This will give you a list of <literal>projects</literal>, where each
|
|
<literal>project</literal> contains general information and a list
|
|
of its <literal>job sets</literal>.
|
|
</para>
|
|
|
|
<para>
|
|
<emphasis role="strong">Example</emphasis>
|
|
</para>
|
|
|
|
<programlisting>
|
|
curl -i -H 'Accept: application/json' \
|
|
https://hydra.nixos.org
|
|
</programlisting>
|
|
|
|
<para>
|
|
<emphasis role="strong">Note:</emphasis> this response is truncated
|
|
</para>
|
|
|
|
<programlisting>
|
|
GET https://hydra.nixos.org/
|
|
HTTP/1.1 200 OK
|
|
Content-Type: application/json
|
|
|
|
[
|
|
{
|
|
"displayname": "Acoda",
|
|
"name": "acoda",
|
|
"description": "Acoda is a tool set for automatic data migration along an evolving data model",
|
|
"enabled": 0,
|
|
"owner": "sander",
|
|
"hidden": 1,
|
|
"jobsets": [
|
|
"trunk"
|
|
]
|
|
},
|
|
{
|
|
"displayname": "cabal2nix",
|
|
"name": "cabal2nix",
|
|
"description": "Convert Cabal files into Nix build instructions",
|
|
"enabled": 0,
|
|
"owner": "simons@cryp.to",
|
|
"hidden": 1,
|
|
"jobsets": [
|
|
"master"
|
|
]
|
|
}
|
|
]
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Get a single project</title>
|
|
|
|
<para>
|
|
To get a single <literal>project</literal> by identifier:
|
|
</para>
|
|
|
|
<programlisting>
|
|
GET /project/:project-identifier
|
|
Accept: application/json
|
|
</programlisting>
|
|
|
|
<para>
|
|
<emphasis role="strong">Example</emphasis>
|
|
</para>
|
|
|
|
<programlisting>
|
|
curl -i -H 'Accept: application/json' \
|
|
https://hydra.nixos.org/project/hydra
|
|
</programlisting>
|
|
|
|
<programlisting>
|
|
GET https://hydra.nixos.org/project/hydra
|
|
HTTP/1.1 200 OK
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"description": "Hydra, the Nix-based continuous build system",
|
|
"hidden": 0,
|
|
"displayname": "Hydra",
|
|
"jobsets": [
|
|
"hydra-master",
|
|
"hydra-ant-logger-trunk",
|
|
"master",
|
|
"build-ng"
|
|
],
|
|
"name": "hydra",
|
|
"enabled": 1,
|
|
"owner": "eelco"
|
|
}
|
|
</programlisting>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Get a single job set</title>
|
|
|
|
<para>
|
|
To get a single <literal>job set</literal> by identifier:
|
|
</para>
|
|
|
|
<programlisting>
|
|
GET /jobset/:project-identifier/:jobset-identifier
|
|
Content-Type: application/json
|
|
</programlisting>
|
|
|
|
<para>
|
|
<emphasis role="strong">Example</emphasis>
|
|
</para>
|
|
|
|
<programlisting>
|
|
curl -i -H 'Accept: application/json' \
|
|
https://hydra.nixos.org/jobset/hydra/build-ng
|
|
</programlisting>
|
|
|
|
<programlisting>
|
|
GET https://hydra.nixos.org/jobset/hydra/build-ng
|
|
HTTP/1.1 200 OK
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"errormsg": "evaluation failed due to signal 9 (Killed)",
|
|
"fetcherrormsg": null,
|
|
"nixexprpath": "release.nix",
|
|
"nixexprinput": "hydraSrc",
|
|
"emailoverride": "rob.vermaas@gmail.com, eelco.dolstra@logicblox.com",
|
|
"jobsetinputs": {
|
|
"officialRelease": {
|
|
"jobsetinputalts": [
|
|
"false"
|
|
]
|
|
},
|
|
"hydraSrc": {
|
|
"jobsetinputalts": [
|
|
"https://github.com/NixOS/hydra.git build-ng"
|
|
]
|
|
},
|
|
"nixpkgs": {
|
|
"jobsetinputalts": [
|
|
"https://github.com/NixOS/nixpkgs.git release-14.12"
|
|
]
|
|
}
|
|
},
|
|
"enabled": 0
|
|
}
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title>List evaluations</title>
|
|
|
|
<para>
|
|
To list the <literal>evaluations</literal> of a
|
|
<literal>job set</literal> by identifier:
|
|
</para>
|
|
|
|
<programlisting>
|
|
GET /jobset/:project-identifier/:jobset-identifier/evals
|
|
Content-Type: application/json
|
|
</programlisting>
|
|
|
|
<para>
|
|
<emphasis role="strong">Example</emphasis>
|
|
</para>
|
|
|
|
<programlisting>
|
|
curl -i -H 'Accept: application/json' \
|
|
https://hydra.nixos.org/jobset/hydra/build-ng/evals
|
|
</programlisting>
|
|
|
|
<para>
|
|
<emphasis role="strong">Note:</emphasis> this response is truncated
|
|
</para>
|
|
|
|
<programlisting>
|
|
GET https://hydra.nixos.org/jobset/hydra/build-ng/evals
|
|
HTTP/1.1 200 OK
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"evals": [
|
|
{
|
|
"jobsetevalinputs": {
|
|
"nixpkgs": {
|
|
"dependency": null,
|
|
"type": "git",
|
|
"value": null,
|
|
"uri": "https://github.com/NixOS/nixpkgs.git",
|
|
"revision": "f60e48ce81b6f428d072d3c148f6f2e59f1dfd7a"
|
|
},
|
|
"hydraSrc": {
|
|
"dependency": null,
|
|
"type": "git",
|
|
"value": null,
|
|
"uri": "https://github.com/NixOS/hydra.git",
|
|
"revision": "48d6f0de2ab94f728d287b9c9670c4d237e7c0f6"
|
|
},
|
|
"officialRelease": {
|
|
"dependency": null,
|
|
"value": "false",
|
|
"type": "boolean",
|
|
"uri": null,
|
|
"revision": null
|
|
}
|
|
},
|
|
"hasnewbuilds": 1,
|
|
"builds": [
|
|
24670686,
|
|
24670684,
|
|
24670685,
|
|
24670687
|
|
],
|
|
"id": 1213758
|
|
}
|
|
],
|
|
"first": "?page=1",
|
|
"last": "?page=1"
|
|
}
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Get a single build</title>
|
|
|
|
<para>
|
|
To get a single <literal>build</literal> by its id:
|
|
</para>
|
|
|
|
<programlisting>
|
|
GET /build/:build-id
|
|
Content-Type: application/json
|
|
</programlisting>
|
|
|
|
<para>
|
|
<emphasis role="strong">Example</emphasis>
|
|
</para>
|
|
|
|
<programlisting>
|
|
curl -i -H 'Accept: application/json' \
|
|
https://hydra.nixos.org/build/24670686
|
|
</programlisting>
|
|
|
|
<programlisting>
|
|
GET /build/24670686
|
|
HTTP/1.1 200 OK
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"job": "tests.api.x86_64-linux",
|
|
"jobsetevals": [
|
|
1213758
|
|
],
|
|
"buildstatus": 0,
|
|
"buildmetrics": null,
|
|
"project": "hydra",
|
|
"system": "x86_64-linux",
|
|
"priority": 100,
|
|
"releasename": null,
|
|
"starttime": 1439402853,
|
|
"nixname": "vm-test-run-unnamed",
|
|
"timestamp": 1439388618,
|
|
"id": 24670686,
|
|
"stoptime": 1439403403,
|
|
"jobset": "build-ng",
|
|
"buildoutputs": {
|
|
"out": {
|
|
"path": "/nix/store/lzrxkjc35mhp8w7r8h82g0ljyizfchma-vm-test-run-unnamed"
|
|
}
|
|
},
|
|
"buildproducts": {
|
|
"1": {
|
|
"path": "/nix/store/lzrxkjc35mhp8w7r8h82g0ljyizfchma-vm-test-run-unnamed",
|
|
"defaultpath": "log.html",
|
|
"type": "report",
|
|
"sha256hash": null,
|
|
"filesize": null,
|
|
"name": "",
|
|
"subtype": "testlog"
|
|
}
|
|
},
|
|
"finished": 1
|
|
}
|
|
</programlisting>
|
|
</section>
|
|
|
|
</chapter>
|
|
|
|
<!--
|
|
Local Variables:
|
|
indent-tabs-mode: nil
|
|
ispell-local-dictionary: "american"
|
|
End:
|
|
-->
|