Skip to content

Commit

Permalink
Adds documentation for the external API (#441)
Browse files Browse the repository at this point in the history 
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.
  • Loading branch information
@rzetterberg @domenkozar
rzetterberg authored and domenkozar committed Apr 1, 2017
1 parent 90870f1 commit 3e0ee24
Show file tree
Hide file tree
Showing 2 changed files with 339 additions and 0 deletions.
338 changes: 338 additions & 0 deletions doc/manual/api.xml
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:
-->
1 change: 1 addition & 0 deletions doc/manual/manual.xml
View file
Expand Up @@ -63,6 +63,7 @@
<xi:include href="introduction.xml" />
<xi:include href="installation.xml" />
<xi:include href="projects.xml" />
<xi:include href="api.xml" />
<xi:include href="hacking.xml" />


Expand Down

0 comments on commit 3e0ee24

Please sign in to comment.