![Richard Zetterberg](/assets/img/avatar_default.png)
Documents all the endpoints that can be used to retrieve data from the API without authenticating. Authentication and manipulating data with the API is not documented.
339 lines
7.1 KiB
XML
339 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",
|
|
"releases": [],
|
|
"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",
|
|
"releases": [],
|
|
"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",
|
|
"releases": []
|
|
}
|
|
</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",
|
|
"sha1hash": null,
|
|
"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:
|
|
-->
|