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