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

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