Stewdio API is the central piece of the Stewdio Radio System (SRS). It provides searching and requesting functionality to users and queues songs with the actual streaming daemon (currently only supporting kawa).

• Install the package (buildable via ArchLinux PKGBUILD in contrib) or via python setup.py install (not recommended unless in a venv)
• Set database connection information and other configuration in stewdio-api.conf and/or copy it to /etc/stewdio/api.conf
• Set the database connection information in alembic.ini
• Initialize the database:

  $ PYTHONPATH="." python contrib/init_db.py
  $ alembic stamp head
  

• Run run.sh to start stewdio-api. Kawa should be running already, otherwise stewdio-api will spit out errors

alembic upgrade head

Some restricted API endpoints require an account. Currently, that only includes adding and removing favorites for a user that has a password set.

If a user was created without a password, a password can only be set using CLI interface. This will generate a random password that can be reset using the user update endpoint.

python -m stewdio.user <username>

If no user exists yet, it can be created via the /api/user/creatwe endpoint:

curl 'http://localhost:5000/api/user/create' --user minus:asdf -XPOST -s | jq

Endpoints under /api/user require authenticating with HTTP Basic Authentication, i.e. username and password must be sent in the Authorization header.

To change a user's password, send a request with the new password to the /api/user/update endpoint:

curl 'http://localhost:5000/api/user/create' --user minus:asdf -d '{"password":"newasdf"}' -s | jq

Some endpoints require an API key. One can be created using the /api/user/apikeys/create endpoint by supplying a name for the key (purely informational). The response will contain the API key in the key field in the object in the key field. This key is just shown once.

curl 'http://localhost:5000/api/user/apikeys/create' --user minus:asdf -d '{"name":"cli request script"}' -s | jq .key.key

Some endpoints, like adding and removing favorites, require an API key to be supplied. The user/password credentials are not accepted. The API key can either be passed via a GET parameter apikey, or in the Authorization header as Basic authentication. Adding the current song to favorites looks as follows:

curl 'http://localhost:5000/api/favorites/minus/playing' --user '<api key>:' -XPUT
curl 'http://localhost:5000/api/favorites/minus/playing' --user 'anything:<api key>' -XPUT
curl 'http://localhost:5000/api/favorites/minus/playing?apikey=<api key>' -XPUT