A Python-based, containerized microservice.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Julian b48ac04a80 [app] fix validation bug 3 months ago
app [app] fix validation bug 3 months ago
docker [changelog, todo] bump version tp 0.32.0 3 months ago
make [local, make] add 'bandit' requirement & 'security' target to local toolchain 3 months ago
proxy/conf.d [proxy, wiki] refactor nginx config, reflect new repo structure 4 months ago
server [server] refactor gunicorn config and requirements 4 months ago
spec [spec] update components, add notes paths 3 months ago
tests [tests] add more integration tests for note and user items 3 months ago
wiki [wiki] refactor urls 3 months ago
.dockerignore [dockerignore] cleanup 3 months ago
.editorconfig [makefile, readme, dotfiles] rename 5 months ago
.env.template [env] rename template for better file type detection 4 months ago
.gitignore [gitignore, makefile] exclude .env and remove it 5 months ago
CHANGELOG.md [changelog, todo] bump version tp 0.32.0 3 months ago
LICENSE [license] fill in copyright 1 year ago
Makefile [tests] move unit test config and rename target to 'unit-test' 3 months ago
README.md [wiki] move and link to readme 3 months ago
TODO.md [wiki] move and link to readme 3 months ago
requirements.txt [local, make] add 'bandit' requirement & 'security' target to local toolchain 3 months ago



A Python-based microservice featuring a RESTful API for user management and an interactive API documentation.

API features

  • schemas
    • API (OpenAPI), entities (Webargs)
  • requests
    • authentication header: Api-Key
  • responses
    • entities & errors in JSON
    • partial entities (nestable): ?fields=uuid,name,notes(uuid,content)
  • caching
    • on GET requests (for positive responses)
    • with invalidation on POST|PATCH|DELETE requests
  • statelessness


Install these through your system's package manager:


  • Python 3.8+
  • virtualenv 16+
  • GNU Make 4+
  • Docker 19.03+
  • Docker Compose 1.25+
  • cURL 7+
  • any browser


  • GNU sed 4+
  • OpenSSL 1.1+


Add yourself to the docker group with:

sudo gpasswd -a ${USER} docker


Create a .env file from the template and replace <SECRET> with encoded randomness:

cp .env.template .env && while grep -q '<SECRET>' .env; do sed -i '0,/<SECRET>/ s__'$(openssl rand -base64 42)'_' .env; done

Note: the .env file is excluded from being committed via .gitignore, given that it now contains secrets.


Run the default tooling steps to get everything up and running:

make all

Browse the docs

Visit localhost/docs in your browser to see the interactive documentation rendered from the OpenAPI specification.

You'll get an overview of currently existing API routes (methods and paths), parameters and entities.

Query the API

Source the .env file and export needed variables into environment:

set -a; . .env; set +a

Request the user collection:

# create a few users
time curl -iH "$API_KEY_HEADER" -H "$JSON_HEADER" -d '{"name":"foobar"}' localhost/v1/users
time curl -iH "$API_KEY_HEADER" -H "$JSON_HEADER" -d '{"name":"bingo"}' localhost/v1/users
# get all users
time curl -iH "$API_KEY_HEADER" localhost/v1/users
# get all users, filtered by name
time curl -iH "$API_KEY_HEADER" localhost/v1/users?filter-by-name=foo
# get all users, partially for these fields (escape `,`)
time curl -iH "$API_KEY_HEADER" 'localhost/v1/users?fields=name,email'
# get all users, filtered & partially for these fields (escape `&` and `,`)
time curl -iH "$API_KEY_HEADER" 'localhost/v1/users?filter-by-name=foo&fields=name,notes(content)'

Request a user item (replace UUID with one from the previous responses):

# get a user
time curl -iH "$API_KEY_HEADER" localhost/v1/users/{UUID}
# get a user, partially for these fields (escape `,`)
time curl -iH "$API_KEY_HEADER" 'localhost/v1/users/{UUID}?fields=name,notes(uuid,content)'
# update a user
time curl -iH "$API_KEY_HEADER" -X PATCH -H "$JSON_HEADER" -d '{"email":"foo@bar.com"}' localhost/v1/users/{UUID}
# delete a user
time curl -iH "$API_KEY_HEADER" -X DELETE localhost/v1/users/{UUID}

Analogous, you can request the note collection & items.

Query auxiliary routes

Get app server health status and environment dump:

time curl -sw '\n' -H "${API_KEY_HEADER}" localhost/health | python -m json.tool
time curl -sw '\n' -H "${API_KEY_HEADER}" localhost/envdump | python -m json.tool

Shut down

Stop and remove all containers:

make down

Run time state gets persisted in the database volume (permanently) and in the cache volume (briefly).

Further reading