From 3e0ee24b87ee65660ae5a14688e74819aef427a8 Mon Sep 17 00:00:00 2001 From: Richard Zetterberg Date: Sat, 1 Apr 2017 11:20:49 +0200 Subject: [PATCH] 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. --- doc/manual/api.xml | 338 ++++++++++++++++++++++++++++++++++++++++++ doc/manual/manual.xml | 1 + 2 files changed, 339 insertions(+) create mode 100644 doc/manual/api.xml diff --git a/doc/manual/api.xml b/doc/manual/api.xml new file mode 100644 index 00000000..435af049 --- /dev/null +++ b/doc/manual/api.xml @@ -0,0 +1,338 @@ + + + Using the external API + + + To be able to create integrations with other services, Hydra exposes + an external API that you can manage projects with. + + + + The API is accessed over HTTP(s) where all data is sent and received + as JSON. + + + + Creating resources requires the caller to be authenticated, while + retrieving resources does not. + + + + The API does not have a separate URL structure for it's endpoints. + Instead you request the pages of the web interface as + application/json to use the API. + + +
+ List projects + + + To list all the projects of the Hydra install: + + + +GET / +Accept: application/json + + + + This will give you a list of projects, where each + project contains general information and a list + of its job sets. + + + + Example + + + +curl -i -H 'Accept: application/json' \ + https://hydra.nixos.org + + + + Note: this response is truncated + + + +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" + ] + } +] + +
+ +
+ Get a single project + + + To get a single project by identifier: + + + +GET /project/:project-identifier +Accept: application/json + + + + Example + + + +curl -i -H 'Accept: application/json' \ + https://hydra.nixos.org/project/hydra + + + +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": [] +} + + +
+ +
+ Get a single job set + + + To get a single job set by identifier: + + + +GET /jobset/:project-identifier/:jobset-identifier +Content-Type: application/json + + + + Example + + + +curl -i -H 'Accept: application/json' \ + https://hydra.nixos.org/jobset/hydra/build-ng + + + +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 +} + +
+ +
+ List evaluations + + + To list the evaluations of a + job set by identifier: + + + +GET /jobset/:project-identifier/:jobset-identifier/evals +Content-Type: application/json + + + + Example + + + +curl -i -H 'Accept: application/json' \ + https://hydra.nixos.org/jobset/hydra/build-ng/evals + + + + Note: this response is truncated + + + +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" +} + +
+ +
+ Get a single build + + + To get a single build by its id: + + + +GET /build/:build-id +Content-Type: application/json + + + + Example + + + +curl -i -H 'Accept: application/json' \ + https://hydra.nixos.org/build/24670686 + + + +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 +} + +
+ + + + diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml index c9273cde..75e53152 100644 --- a/doc/manual/manual.xml +++ b/doc/manual/manual.xml @@ -63,6 +63,7 @@ +