Skip to content

Latest commit

 

History

History
103 lines (63 loc) · 4.79 KB

README.md

File metadata and controls

103 lines (63 loc) · 4.79 KB

API

TOC

Overview

The API is a lightweight abstraction and supports RESTful operations for JSON encoded objects.

Configuration API

Structure

Multiple sets of configurations can be managed by naming different instances. Within an instance, multiple sections can be defined.

The value associated with a key is encoded as a JSON object and not validated beyond being valid JSON. Lightweight abstraction means the responsibility for validating and understanding encoded JSON data rests with the consumers of the API for the value part of anything stored in KVS.

If section is not specified in the API call, the operation will assume section to be a wildcard and potentially match multiple sections within the same instance if they exist. Each section is returned as a numbered enumeration of the resulting array. The response message in the body of the request indicates number of sections were matched with the property "sections:" with an integer value.

If instance is not specified in the API call, the operation will assume instance to be a wildcard and potentially match multiple instances. Each instance is returned as a numbered enumeration of the resulting array. The response message in the body of the request indicates number of instances were matched with the property "instances:" with an integer value.

Backend

Configuration is stored in a Redis-compatible key-value store (KVS). Keys are encoded in KVS as config:<instance>:<section>, like config:ak7vv:n0nbh for a configuration section n0nbh within the instance ak7vv. The KVS is always assumed to be local unless specified otherwise (REDIS_HOST, REDIS_PORT environment variables). A single API instance can only be associated with a single KVS endpoint.

One example of a consumer of the API are the CLI commands in ../cli that invoke REST API calls to implement the CLI backend. Components integrated with Hamframe can use the API to retrieve or modify configuration sections.

Using the API

The API is implemented as a Docker container running FastAPI. By default, the API will open 65432/tcp unless you specify LISTENER_PORT environment variable to be something else. The API will listen on localhost unless you specify something else with LISTENER_HOST environment variable. If you need access from outside the host, specify the LISTENER_HOST to be the IP address or DNS name of a single interface or 0.0.0.0 to listen on all.

The API is versioned as, for example, "/v1/configuration" to allow for what would otherwise be breaking changes over time. The intent is to support GET, PUT, PATCH, and DELETE for all objects, but the completeness may vary. Root "/" has no significance.

Container

This repo will trigger a GitHub Actions workflow to build a new container (for linux/amd64 and linux/arm64) and push a successful build to Docker Hub ak7vv/hamframe-api if anything that runs in the container is modified in the repo.

You can run this container with

    docker run \
        --name api \
        --publish 65432:65432 \
        ak7vv/hamframe-api

and optionally you can pass environment variables like

    docker run \
        --name api \
        --env LOG_LEVEL=debug \
        --env LISTENER_HOST=0.0.0.0 \
        --publish 65432:65432 \
        ak7vv/hamframe-api

Remember that the environment variables always have to be defined before the container name and not after.

python from .venv:

You can also run the API by starting it directly from python inside a virtual environment. This is mainly intended for dev:

    python api.py

and optionally you can pass environment variables like

    export LOG_LEVEL=debug \
    export LISTENER_HOST=0.0.0.0 \
    python api.py

Use the Container if you intend to use this code.

Testing

/tests contains the pytest testing framework integrated with FastAPI and will be expanded over time. Run with 'pytest'.

You can find the beginnings in tests/test_api.py.

Test coverage is poor at this time. (Issue #)

OpenAPI docs

FastAPI is self-documenting as OpenAPI (the artist formerly known as Swagger), which can be found at

http://host_ip:65432/openapi.json

You can also find human-readable variants here:

http://host_ip:65432/docs
http://host_ip:65432/redoc

where you can learn about the API verbs and attributes as well as exercise the API.