Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add hydra OpenAPI description #750

merged 20 commits into from May 11, 2020

Add hydra OpenAPI description #750

merged 20 commits into from May 11, 2020


Copy link

gilligan commented May 4, 2020

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


  • 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


  • Document all methods for all paths
    • create project
    • create jobset
    • evaluate jobset
    • search
  • Add missing descriptions
    • JobsetEvalInput.revision
    • JobsetEvalInput.value
    • JobsetEvalInput.dependency
    • BuildProduct.defaultpath
    • Build.releasename
    • JobsetInput.jobsetinputalts
  • Hosting api.html somewhere (

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 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 and play with it
Copy link

edolstra commented May 6, 2020

Looks good to me.

  • JobsetInput.jobsetinputalts should be removed since we got rid of the concept of input alternatives a long time ago (#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 Outdated Show resolved Hide resolved
hydra.yaml Outdated Show resolved Hide resolved
hydra.yaml Outdated Show resolved Hide resolved
hydra.yaml Outdated Show resolved Hide resolved
hydra.yaml Outdated Show resolved Hide resolved
gilligan added 5 commits May 6, 2020
- drop releases/releasename
- document dependency
- document defaultpath
Add `PUT /project/{id}`
Copy link

grahamc commented May 8, 2020

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

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

@gilligan gilligan mentioned this pull request May 8, 2020
Copy link

grahamc commented May 11, 2020

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)

Copy link
Contributor Author

gilligan commented May 11, 2020

@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/", 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.

@gilligan gilligan changed the title WIP: Add hydra OpenAPI description Add hydra OpenAPI description May 11, 2020
@grahamc grahamc merged commit 41d7039 into NixOS:master May 11, 2020
2 checks passed
2 checks passed
@gilligan gilligan deleted the gilligan:swagger-config branch May 11, 2020
Copy link

nixos-discourse commented May 11, 2020

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

4 participants
You can’t perform that action at this time.