CodeGen Micro-service

Webservice to generate codes, used by us to generate participant IDs in the format we want from our survey software. From javascript a payload needs to be sent.

Setting up the platform

First create and load a virtual environment for this application and pip install the required packages.

Next set up config.py (this is a basic flask application with flask-sqlalchemy, an example configuration is included below) and create a database with an admin account. The final command (flask run) will start a development server locally.

flask initdb
flask add-admin admin yourpassword
flask run

Log into, http://localhost:5000/admin/ (assuming the site is hosted on http://localhost:5000) and use the CRUD interface to create a new project.

The project name is important, as this will need to be passed through to get a code back. The prefix defines what the code will look like. Optionally a description can be provided.

Working with the platform

Generating Codes

Using e.g. jQuery a JSON payload should be sent to http://localhost:5000/generate/code, with the name of the project (added through the admin interface) and an origin (a code that is stored in the DB, this can be anything)

Payload example:

{
  "project": "Project Name",
  "origin": "Source of Request"
}

Using curl you could use the commmand below to get the next code from the project Test.

 curl -X POST -H "Content-Type: application/json" -d '{ "project": "Test", "origin": "Curl" }' http://localhost:5000/generate/code

Optionally, a participant ID (or name, email address, ...) can be included. This is stored encrypted along with the generated code. This option allows later on to link a participant to the code again in case of emergency (not implemented yet)

{
  "project": "Project Name",
  "origin": "Source of Request",
  "participant": "Name of participant"
}

If successful the server will respond with another JSON object, with a status code (should be "success") and the code that was generated.

{
    "status": "success",
    "code": "TEST.00001"
}

Checking if codes exist

To check if a code exists, a request (post), with the fields code and project needs to be sent to http://localhost:5000/check/code

{
    "project": "test",
    "code": "TEST.00001"
}

If the project and the code exist, the response will be

{
    "status": "success",
    "code": "TEST.00001",
    "exists": true
}

If the project exists, but the code does not, the response will be

{
    "status": "success",
    "code": "TEST.00001",
    "exists": false
}

If the project does not exist, the following response will be provided (with error code 417)

{
    "status": "error",
    "message": "Project Test2 not found"
}

Setting up config.py

Below is an example config.py file, any parameter for Flask, Flask-SQLAlchemy, Flask-Limiter, Flask-CORS, ... can be specified here.

import os

basedir = os.getcwd()

DEBUG = False
TESTING = False

# create a .env file with the secret key !
SECRET_KEY = os.getenv("SECRET_KEY", "debug_key")

# Database settings, database location and path to migration scripts
SQLALCHEMY_DATABASE_URI = "sqlite:///" + os.path.join(
    basedir, "db", "generated_codes.db"
)
SQLALCHEMY_MIGRATE_REPO = os.path.join(basedir, "db", "migration")
SQLALCHEMY_TRACK_MODIFICATIONS = False
SQLALCHEMY_ECHO = DEBUG

CORS_ORIGINS = ['*']

Using .env to set a secret key

The example config.py gets the SECRET_KEY from a .env file when possible. Put a .env file in the directory with the following line to set the secret key for the application.

SECRET_KEY=random_set_of_characters