Add hydra OpenAPI description #750

gilligan · 2020-05-04T16:24:27Z

Overview
This is a WIP attempt to define and publish an OpenApi 3.0 specification for hydra "REST" interface. The specification is written in yaml as hydra.yaml and would be added to the repository along with a browsable/explorable view which can also be used to trigger requests (currently hosted here

Motivation

hydra generally lacks documentation so this should be a good start
there is also tooling to generate server/client code based on the specification. I tried this and i got a working python client that could list projects at first try
down the road we could also nicely integrate this for testing: generate a client based on the specification and use the client to make requests against the API
currently there isn't much in the way of versioning hydra so a description like be helpful with that

TODOs

Note that the above probably isn't a comprehensive list of things that would mean that everything is covered but if possible i'd like to get a first sensible version merged and then iterate and improve on it.

Help needed:
I am going to need some help getting this over the finishing line.

I already received some help from @grahamc with some descriptions but the items listed above are still clear. The easiest way to help out is to look at http://www.tpflug.me/api.html or hydra.yaml directly and help me out with all occurrences of descriptions set to ??? :)
I generally need people to double check if i have written any kind of nonsense and point out missing pieces in the specification.
If you want, you can copy paste hydra.yaml into http://editor.swagger.io/# and play with it

edolstra · 2020-05-06T10:19:07Z

Looks good to me.

JobsetInput.jobsetinputalts should be removed since we got rid of the concept of input alternatives a long time ago (Get rid of jobset alts #279).
Same applies to Build.releasename (in fact we should get rid of the concept of "releases" in Hydra, which nobody uses).
BuildProduct.defaultpath is the default subpath to be used for a build product (e.g. /index.html if the build product is a directory).

hydra.yaml

- drop releases/releasename - document dependency - document defaultpath

Add `PUT /project/{id}`

grahamc · 2020-05-08T15:31:18Z

We can skip hosting api.html by pointing to this:

https://petstore.swagger.io/?url=https://raw.githubusercontent.com/gilligan/hydra/swagger-config/hydra-api.yaml

but changing to the master branch of the nixos/hydra repo.

grahamc · 2020-05-11T13:22:29Z

I think it'd be useful to have this hydra yaml file checked in CI for validity, and maybe even codespell:

$ nix-shell -p codespell --run "codespell hydra-api.yaml
hydra-api.yaml:169: hiddden  ==> hidden

(this is a demo error from a while back, it isn't an error now)

gilligan · 2020-05-11T13:36:16Z

@grahamc I don't mind adding codespell but would like to do so in a follow-up PR if that is OK with you. I just tried locally and codespell is acting up for me in funny ways:

[nix-shell:~/dev/NixOS/hydra]$ codespell hydra-api.yaml
Traceback (most recent call last):
  File "/nix/store/1qmcsm3pqsghccgx7b0s6hlvzppy4v6r-codespell-1.16.0/bin/.codespell-wrapped", line 4, in <module>
    import re
  File "/nix/store/55b9ip7xkpimaccw9pa0vacy5q94f5xa-python3-3.7.6/lib/python3.7/re.py", line 143, in <module>
    class RegexFlag(enum.IntFlag):
AttributeError: module 'enum' has no attribute 'IntFlag'

I did add validation via openapi-generator-cli though. So we do validate the yaml file at least. i can open an issue to add codespell validation and assign it to myself once this is merged.

nixos-discourse · 2020-05-11T19:21:15Z

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/tweag-nix-dev-update-3/7154/1

gilligan added 5 commits May 3, 2020 01:09

Add swagger config

c1591b4

Add hydra api info to the README

acc0c3a

hydra.yaml: added some more descriptions

ff73eee

Add /login

54601c5

Add 404/403 responses

4320589

edolstra reviewed May 6, 2020

View reviewed changes