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

README.md

flask-restful-demo

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

Prerequisites

Install these through your system's package manager:

Required

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

Optional

  • GNU sed 4+
  • OpenSSL 1.1+

Docker

Add yourself to the docker group with:

sudo gpasswd -a ${USER} docker

Config

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.

Usage

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