REST API¶
Scrooge provides public REST API described by OpenAPI-compliant
schema, which is available for consumption by external
programs/clients at /scrooge/api/schema.json
.
On top of this schema, we provide swagger-ui , which is available at
/scrooge/api
or /api
endpoint (the latter just redirects to
the former). It serves both as documentation and convenience tool,
that is meant to facilitate human interaction with our API and improve
its discoverability.
Notes for Scrooge developers/administrators¶
API schema is defined in file pointed by API_SCHEMA_FILE
setting (by default
ralph_scrooge.media.api_schema.yaml
). This file, in YAML format is meant for
editing and feeding swagger-ui
during development. For production though,
you should generate a JSON file from it. There’s a management command scrooge
generate_json_schema
, which is meant exactly for that. So basically, YAML file
is a source file, while JSON should be seen as kind of artifact, which is not
meant to be edited directly (it is minified BTW), and shouldn’t be kept in
Scrooge’s repo.
There is one important setting related to API schema - SCROOGE_HOST
- which
should be filled if you want to provide Scrooge’s REST API schema to your
clients (and swagger-ui is one of them) - see the comment in
ralph_scrooge.settings.base
for additional info on this.