It would be nice to update the spec, to make [API docs](https://observatorium.io/docs/api) clearer and more descriptive as discussed in https://github.com/observatorium/observatorium/pull/483.