From 3c671100c7a6ab08aead65da0f5c9d84a213842a Mon Sep 17 00:00:00 2001 From: Interitio Date: Wed, 11 Jun 2025 20:13:50 +1000 Subject: [PATCH] docs: Add some usage docs. --- README.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..c409e41 --- /dev/null +++ b/README.md @@ -0,0 +1,33 @@ +# Dreamspace API Demo + +This repository contains some demo code to test and play with the Dreamspace API. + +NOTE: Do *not* use these demos incautiously on the live production API. The demo flows test a variety of API endpoints, including one that deletes all the users stored by the API. + +## Usage +First make sure you install the packages listed in `requirements.txt`. The typical way of doing this is using a venv and pip. +``` +python -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt +``` + +Then run the demos with +``` +python src/demo.py --url BASE_URL --token SecureToken +``` +Replace `BASE_URL` with the url of the API you are using. For example https://dreams.thewisewolf.dev or http://localhost:8000 +Replace `SecureToken` with the API token used by the target API + + +The basic demo will ***wipe all the users in the API*** for a clean start, then create and submit several events with documents and stamps to the API. +It will then download these event documents and save them as `png`s in a folder called `users`. + +To understand and modify the demo flow, see `src/demos.py`. In particular, the method `run_demos` is what is called to actually run the demonstration. + + +## Structure +- `src/demo.py` is the entry point with nothing of note except the command line argument parser. +- `src/client.py` contains a basic API client exposing (almost) all of the API routes as python methods. Notable exceptions include nested routes (e.g. `POST /events/{event_id}/document/stamps` is not supported, instead use the equivalent `POST /documents/{document_id}/stamps`.), and some minor routes such as `GET /users/{user_id}/wallet` which were only included for completeness in the original API. +- `src/drawing.py` contains some really basic image creation methods to simulate card images, along with the base64 encoder and decoder for images. +- `src/demos.py` contains the sample data, and example flows to create events and stamp the resulting documents. The `run_demos` method should be edited to modify which demonstrations are actually run.