Engine API Server

Overview

The Project serves the Engine API and handles state management of multiple Engine instances.

The Engine API stores and provides following information:

• Playlogs: A history of all audio titles being played by the Engine. This is used for detailed reports.
• Track Service: Same as track service, but stripped-down information. Used for implementing a track service feature on the radio's website.
• Active Source: In redundant deployment scenarios the API stores and shares information on which engine instance is active. This could be extended to other audio sources.
• Health Information: In case of some critical issue, the health status of the respective engine is stored.

You can find details on the available API endpoints here: https://app.swaggerhub.com/apis/AURA-Engine/engine-api/1.0.0

Deployment Modes

AURA Engine allows single and redundant deployments.

Single Deployment

This is the most simple case. In that scenario the Engine API is deployed on the same host as the Engine itself.

In your live deployment you might not want to expose the API directly on the web. For security reasons it's highly recommended to guard it using something like a reverse proxy.

Redundant Deployment

In this scenario there are two Engine instances. Here you will need deploy one Engine API on the host of each Engine instance. Additionally you'll have to deploy a third, so-called "Syncronization Node" of the Engine API. The sync instanc of Engine API is in charge of synchronizing playlogs, health information etc.

Getting started

Requirements

If you are not planning to go with Docker or just want to setup a local development environment, then you'll need:

Python 3.7+ MariaDB Virtualenv

Installation

Create a virtual environment for your Python dependencies:

virtualenv -p python3.7 python

Install the required dependencies:

pip3 install -r requirements.txt
# Additional requirements for the chosen database
pip3 install -r contrib/mariadb-requirements.txt
# Create database and user (change password in script)
sudo mysql -u root -p < contrib/mariadb-database.sql

Configuration

Copy the the sample configuration file in ./config/sample/sample-production.engine-api to config and edit the file. First update the main configuration and then configure the type of federation. Depending on how you want to run your Engine API node and where it is deployed, you'll needed to uncomment one of these federation sections:

To avoid any malfunction it is important that any other node-type configurations are commented out.

Engine 1 Node

Use this section if you are running AURA Engine standalone or if this is the first API node in a redundant deployment.

Replace localhost and port number with the actual details of your sync node.

# NODE 1
host_id=1
sync_host="http://localhost:8010"

Engine 2 Node

In case this is the second API node in a redundant deployment.

Replace localhost and port number with the actual details of your sync node.

# NODE 2
host_id=2
sync_host="http://localhost:8010"

Synchronization Node

This is the synchronization instance in a redundant setup. This instance combines all valid information from coming from Engine API 1 and 2.

Replace localhost and port number with the actual details of your main nodes.

# NODE SYNC
host_id=0
main_host_1="http://localhost:8008"
main_host_2="http://localhost:8009"
default_source=1
sync_interval=3600
sync_batch_size=100
sync_step_sleep=0.23

Running the Server

Development

To run the API in an local development server execute:

./run.sh api-dev

For convenience running a plain ./run.sh also starts the development server.

When you'll need to run all three nodes to do testing during development you can run:

./run.sh api-test-0 # Sync Node
./run.sh api-test-1 # Node 1
./run.sh api-test-2 # Node 2

Here the run script uses the configurations located in ./test/config.

Production

To run the server for production using Gunicorn, you first need to create the Gunicorn configuration by copying the sample ./config/sample/gunicorn/sample-production.gunicorn.conf.py to your config directory.

Then run this from the root directory:

./run.sh api

Running with Docker

To run the server on a Docker container, please execute the following from the root directory:

# Building the image
./run.sh docker:build

# Push the current image to dockerhub.com
./run.sh docker:push

# Starting up a container
./run.sh docker:api

Using the API

You can find details on the available API endpoints here: https://app.swaggerhub.com/apis/AURA-Engine/engine-api/1.0.0

Adding some entry to the playlog:

curl -d '{ "track_start": "2020-06-27 19:14:00", "track_artist": "Mazzie Star", "track_title": "Fade Into You", "log_source": 1 }' -H "Content-Type: application/json" -X POST http://localhost:8008/api/v1/playlog/store

This newly added entry can be queried using your browser in one of the following ways:

# Get the latest entry
http://localhost:8008/api/v1/trackservice/current
# Get a set of the most recent entries
http://localhost:8008/api/v1/trackservice/
# Filter some specific page (the three most recent entries)
http://localhost:8008/api/v1/trackservice?page=0&limit=3

All other API endpoints are listed in the interactive documentation.

http://localhost:8008/api/v1/ui/

Your OpenAPI definition lives here:

http://localhost:8008/api/v1/openapi.json

Testing

To launch the integration tests, use tox:

sudo pip install tox
./run.sh test

Note, the test-cases are currently not functional.

About

This project is based on a swagger-enabled Flask server using an API First approach. It also uses the Connexion library on top of Flask.