Adds documentation for the external API (#441)

[?]

Apr 1, 2017, 9:20 AM

GRMV5GEWXL5HRCQ5AST22ATEPO3VNF4TSJWLYT3J5GPCM2CGRK4AC

Dependencies

[2] DWQCLOPQ Tweaks for nix-shell
[*] 6A6CZ7SC draft manual
[*] 5AKAE3R6 start of hydra manual
[*] PKE6I67S doc: Import the "Creating Projects" chapter by Visser & Dolstra.

Change contents

file addition: api.xml (----------)

[4.18]

<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>


edit in doc/manual/manual.xml at line 66

[6.112]

[2.318]

<xi:include href="api.xml" />