/needforheat-server-api

Source code and deployable packages for the Twomes Backoffice API

Primary LanguageGoApache License 2.0Apache-2.0

NeedForHeat Server API

GitHub License Project Status badge

API for NeedForHeat data collection platform to enable research.

Table of contents

Deploying

For our process to deploy the API to our public server, or update it, see these links:

Prerequisites

The NeedForHeat API is available as a Docker image. You will need to install Docker to run it.

Images

See all available images:

  • Use the latest tag to get the latest stable release built from a tagged GitHub release.
  • Use the main tag to get the latest development release, built directly from the main branch.

Docker Compose (more information)

services:
  web:
    container_name: needforheat-server-api-web
    build: .
    ports:
      - 8080:8080
    volumes:
      - ./data:/data
    environment:
      - NFH_DSN=root:needforheat@tcp(db:3306)/needforheat
      - NFH_BASE_URL=http://localhost:8080
      - NFH_DOWNLOAD_TIME=04h00m # 04:00 UTC
    depends_on:
      - db

  db:
    container_name: needforheat-server-api-db
    image: mariadb:latest
    ports:
      - 3306:3306
    volumes:
      - data:/var/lib/mysql
    environment:
      - MYSQL_DATABASE=needforheat
      - MYSQL_ROOT_PASSWORD=needforheat

volumes:
  data:

Developing

Requirements

Running

Make sure Docker is running on your local machine, then start the service from a command line terminal from the root of this repository:

docker compose up --build

This generates log messages from both the web and the db component. Just keep this running in your terminal.

The API is now available on http://localhost:8080/.

Create a new admin account to use the admin endpoints:

docker exec -i <container-name> needforheat-server-api admin create -n <name>

Substitute <container-name> with the name of the container. Running it locally should be needforheat-server-api-web

Substitute <name> with the name of the admin account you want to create.

Example output of running the command, with johndoe as admin name:

Admin "johndoe" created. Authorization token: eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJUd29tZXNBUEl2MiIsInN1YiI6IjQiLCJleHAiOjE3MTU3MzEyMDAsIm5iZiI6MTY4NDE1MjA4OSwiaWF0IjoxNjg0MTUyMDg5LCJraW5kIjoiYWRtaW5Ub2tlbiJ9.N_uhPhLsaTq0DVGVPhdfU6Hd2VD0Zb8QxesTaWeILlNkkjQ9Vuxpwe0sfi3Vj0GJgyin2ZilPE6AS-makGm2cg

Copy the authorization token without any spaces.

When finished, type the Ctrl + C key in the first terminal. The container state is preserved, and to restart, simply run docker compose up --build again.

To completely remove all docker containers created above:

docker compose rm

To delete the saved data, remove the data directory in the root of this repository.

Folder structure

This repository tries to implement a DDD approach. While some elements are still too tightly coupled to really call it DDD, the structure still tries te represent DDD as best as possible.

Folder Purpose
.github GitHub Actions workflows and config files
cmd CLI commands
docs Additional documentation
handlers HTTP handlers for API endpoints
internal Utitilities that are not exposed outside of this package
repositories Repositories for domain models. Contains al DB logic
services Services tie repositories and subservices together to perform operations.
swaggerdocs Swagger UI and OpenAPI spec.
needforheat Domain models and logic.

Model diagram

To re-generate the model diagram:

docker run -i --rm vranac/erd < docs/model.er > docs/model.pdf

Usage

Tokens

Most end points require a session token to be provided in an authorization bearer HTTP header. These end points are marked with a 'lock' symbol. Click on the 'Authorize' button at the upper right of the page, or click on the 'lock' symbol at the end point, and paste the session token in the value field. Subsequent calls done through http://localhost:8080/docs will then use the session token.

There are currently three types of tokens:

  • Admin: Used by administrators to manage resources.
  • Account: Used by an account to manage its resources.
  • Device: Used by a measurement device to upload measurements.

Managing admins and cloudfeeds

When the container is running, lookup it's name.

Run the following command to see info about how to manage admins:

docker exec <container-name> needforheat-server-api admin --help

Run the following command to see info about how to manage cloudfeeds:

docker exec <container-name> needforheat-server-api cloudfeed --help

Administrators on our servers

Contact an administrator to get admin access to the API:

  • Henri ter Hofte

License

This software is available under the Apache 2.0 license, Copyright 2021 Research group Energy Transition, Windesheim University of Applied Sciences

Credits

This software is created by:

  • Nick van Ravenzwaaij · @n-vr

Thanks also go to:

Product owner:

We use and gratefully aknowlegde the efforts of the makers of the following source code and libraries:

This README uses badges, by Shield.io, licensed under CC0 v1.0 Universal