NeedForHeat Server API

API for NeedForHeat data collection platform to enable research.

Table of contents

• Deploying
• Developing
• Usage
• License
• Credits

Deploying

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

• Deploy: https://github.com/energietransitie/needforheat-server-configuration#api
• Update: https://github.com/energietransitie/needforheat-server-configuration#updating

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

• Go (minimum 1.22)
• Docker

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:

• Arjan peddemors · @arpe
• Harris Mesic · @labhatorian

Product owner:

• Henri ter Hofte · @henriterhofte

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

• chi, by Peter Kieltyka, Google Inc, licensed under MIT license
• gorm, by Jinzhu, licensed under MIT license
• go-sql-driver/mysql, by go-sql-driver, licensed under Mozilla Public License 2.0
• logrus, by Simon Eskildsen, licensed under MIT license
• golang-jwt/jwt, by Dave Grijalva, licensed under MIT license
• crc16, by sigurn, licensed under MIT license
• swagger-ui, by SmartBear Software Inc., licensed under Apache 2.0 license

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