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 2 years ago
app [app] fix validation bug 2 years ago
docker [changelog, todo] bump version tp 0.32.0 2 years ago
make [local, make] add 'bandit' requirement & 'security' target to local toolchain 2 years ago
proxy/conf.d [proxy, wiki] refactor nginx config, reflect new repo structure 2 years ago
server [server] refactor gunicorn config and requirements 2 years ago
spec [spec] update components, add notes paths 2 years ago
tests [tests] add more integration tests for note and user items 2 years ago
wiki [wiki] refactor urls 2 years ago
.dockerignore [dockerignore] cleanup 2 years ago
.editorconfig [makefile, readme, dotfiles] rename 2 years ago
.env.template [env] rename template for better file type detection 2 years ago
.gitignore [gitignore, makefile] exclude .env and remove it 2 years ago
CHANGELOG.md [changelog, todo] bump version tp 0.32.0 2 years ago
LICENSE [license] fill in copyright 2 years ago
Makefile [tests] move unit test config and rename target to 'unit-test' 2 years ago
README.md [wiki] move and link to readme 2 years ago
TODO.md [wiki] move and link to readme 2 years ago
requirements.txt [local, make] add 'bandit' requirement & 'security' target to local toolchain 2 years 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