Add markdown files for documentation
projects.xml and declarative-projects.xml were merged with xmllint, and
then I ran that to convert files
for i in *.xml; do pandoc -s -f docbook -t markdown $i -o ${i/xml/md}; done
This commit is contained in:
Ismaël Bouya
249
doc/manual/src/api.md
Normal file
249
doc/manual/src/api.md
Normal file
@@ -0,0 +1,249 @@
|
||||
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",
|
||||
"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",
|
||||
"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"
|
||||
}
|
||||
|
||||
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",
|
||||
"defaultpath": "log.html",
|
||||
"type": "report",
|
||||
"sha256hash": null,
|
||||
"filesize": null,
|
||||
"name": "",
|
||||
"subtype": "testlog"
|
||||
}
|
||||
},
|
||||
"finished": 1
|
||||
}
|
||||
Reference in New Issue
Block a user