Documentation: https://hymnsapi.sopherapps.com/docs
This is a general API that can host hymns/songs including their musical notation.
- Rate limited API
- Publicly available READ-ONLY with need for an API Key
- Privately accessible WRITE-ONLY with need of a JWT auth token for admins only
- Very fast, due to use of embedded document-oriented database
- Can have multiple translations for each song
- CLI to do some devOps chores e.g. create new admin users etc.
- Python v3.11+ - the programming language
- FastAPI - web server
- Typer CLI - for CLI commands
- postgres - relational database
- mongodb - database
- sqlalchemy - ORM for rdbms
- asyncpg - to connect to postgres asynchronously
- motor - to connect to mongodb asynchronously
- slowapi - rate-limiting
- pyotp - for one time passwords
- fastapi-mail - for sending emails
Environment Variable | Meaning | Default |
---|---|---|
DB_PATH | database URI | ./db |
LANGUAGES | comma-separated list of languages that the song bank will have | english,runyoro |
API_KEY_LENGTH | the length of the API keys generated | 32 |
RATE_LIMIT | the maximum number of requests per window (e.g. second) allowed from one IP address | 5/minute |
OTP_VERIFICATION_URL | the url where the one-time password (OTP) are to be verified from | |
API_SECRET | the 32-byte API secret for hashing and encrypting stuff in the API | |
JWT_TTL_SECONDS | the JWT token's time-to-live in seconds | 900 |
ENABLE_RATE_LIMIT | the flag for enabling/disabling rate-limiting | true |
MAX_LOGIN_ATTEMPTS | maximum number of attempts to feed in an OTP before being locked out. | 5 |
AUTH_MAIL_SENDER | name of the person to put as email sender for all auth related emails | Hymns API team |
MAIL_USERNAME | SMTP username | |
MAIL_PASSWORD | SMTP password | |
MAIL_PORT | SMTP port | |
MAIL_SERVER | SMTP mail server | |
MAIL_FROM | Sender address | |
MAIL_STARTTLS | For STARTTLS connections | true |
MAIL_SSL_TLS | For connecting over TLS/SSL | false |
MAIL_DEBUG | SMTP mail debug i.e. whether mail is being debugged or not. Useful during development. | 0 |
MAIL_FROM_NAME | Title for Mail | |
MAIL_SUPPRESS_SEND | whether sending of emails should be suppressed | 0 |
MAIL_USE_CREDENTIALS | whether or not to login to their SMTP server. | true |
MAIL_VALIDATE_CERTS | whether to verify the mail server's certificate | true |
MAIL_TIMEOUT | timeout in seconds when sending emails | 60 |
- Clone the repo
git clone [email protected]:sopherapps/hymns-api.git
- Install tailwindcss cli if you haven't already
- Enter the templates folder and run the tailwindcss generation command
cd templates
tailwindcss -i ../static/css/input.css -o ../static/css/output.css --watch
-
Install live server and run it if you are using visual studio code.
-
Start editing your files, as you see the live changes in your browser
- Clone the repo
git clone [email protected]:sopherapps/hymns-api.git
- Copy
.env.example
to.env
and update its contents basing on the settings list
cd hymns-api
cp .env.example .env
- Install requirements
python3 -m venv env
source env/bin/activate
pip install -r requirements/prod.txt
- Run the API app.
gunicorn -w 4 -k uvicorn.workers.UvicornWorker -b :8000 main:app
- Run the CLI app, and see the menu for the different commands
python manage.py --help
- To run tests, stop the app with
Ctrl+C
and run
pytest
Contributions are welcome. The docs have to maintained, the code has to be made cleaner, more idiomatic and faster, and there might be need for someone else to take over this repo in case I move on to other things. It happens!
When you are ready, look at the CONTRIBUTIONS GUIDELINES
Copyright (c) 2023 Martin Ahindura
Licensed under the MIT License
- To God, who has created me, chosen me, saved me and sustains me. (Jeremiah 1: 4-5)
"Sing to the Lord! Give praise to the Lord! He rescues the life of the needy from the hands of the wicked."
-- Jeremiah 20: 13
All glory be to God