From d946497336d44c0261c67e25e9ae6c570dc73a87 Mon Sep 17 00:00:00 2001
From: jo <ljonas@riseup.net>
Date: Tue, 28 Jun 2022 21:24:02 +0200
Subject: [PATCH] chore(api): update README

---
 api/README.md | 60 +++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 44 insertions(+), 16 deletions(-)

diff --git a/api/README.md b/api/README.md
index 53ddf335c..f90aaf42a 100644
--- a/api/README.md
+++ b/api/README.md
@@ -1,7 +1,6 @@
 # LibreTime API
 
-This API provides access to LibreTime's database via a Django application. This
-API supersedes the [PHP API](../legacy/application/controllers/ApiController.php).
+This API provides access to LibreTime's database via a Django application.
 
 ## Deploying
 
@@ -11,34 +10,63 @@ development images too. This method does not automatically reflect changes to
 this API. After any changes, the `libretime-api` systemd service needs
 restarting:
 
-    sudo systemctl restart libretime-api
+```bash
+sudo systemctl restart libretime-api
+```
 
 Connections to the API are proxied through the Apache web server by default.
 Endpoint exploration and documentation is available from
 `http://example.com/api/v2/schema/swagger-ui/`, where `example.com` is the URL
 for the LibreTime instance.
 
-### Development
+## Development
 
-For a live reloading version within Vagrant:
+For development, you can install all required dependencies and loading the environment using the following command:
 
+```bash
+make install
+source .venv/bin/activate
 ```
-vagrant up buster
-# Run through the web setup http://localhost:8080
-vagrant ssh buster
-sudo systemctl stop libretime-api
-sudo systemctl restart libretime-analyzer libretime-celery libretime-liquidsoap libretime-playout
+
+You should be able to lint or format the code or run api commands:
+
+```bash
+make format
+make lint
+
+libretime-api help
+```
+
+In order to work with the database and message queue, you need to start the docker based
+development stack present at the project root:
+
+```bash
+pushd ..
+docker-compose up -d
+popd
+```
+
+You can now run the api tests:
+
+```bash
+make test
+```
+
+### Inside Vagrant
+
+You can develop the api using a live reloading version within Vagrant:
+
+```bash
+vagrant up bullseye
+vagrant ssh bullseye
+
 cd /vagrant/api
 sudo pip3 install -e .
+
+sudo systemctl stop libretime-api
 sudo -u www-data LIBRETIME_DEBUG=True libretime-api runserver 0.0.0.0:8081
 ```
 
-Unit tests can be run in the vagrant environment using
-
-```
-sudo -u www-data LIBRETIME_DEBUG=True libretime-api test libretime_api
-```
-
 ## 3rd Party Licences
 
 `libretime_api/tests/resources/song.mp3`: Steps - Tears On The Dancefloor (Album