Adds documentation for the external API (#441)

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.
This commit is contained in:
Richard Zetterberg 2017-04-01 11:20:49 +02:00 committed by Domen Kožar
parent 90870f1416
commit 3e0ee24b87
2 changed files with 339 additions and 0 deletions

338
doc/manual/api.xml Normal file
View file

@ -0,0 +1,338 @@
<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:
-->

View file

@ -63,6 +63,7 @@
<xi:include href="introduction.xml" /> <xi:include href="introduction.xml" />
<xi:include href="installation.xml" /> <xi:include href="installation.xml" />
<xi:include href="projects.xml" /> <xi:include href="projects.xml" />
<xi:include href="api.xml" />
<xi:include href="hacking.xml" /> <xi:include href="hacking.xml" />