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
Domen Kožar
parent
90870f1416
commit
3e0ee24b87
338
doc/manual/api.xml
Normal file
338
doc/manual/api.xml
Normal 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:
|
||||||
|
-->
|
||||||
|
|
@ -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" />
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue