Bonsai API

Documentation

See API specifications and documentation.

What is it?

This is a Flask-based application programming interface (API) using representational state transfer (REST) using GET and POST methods to quickly and easily query the BONSAI graph database and serve LCA results.

The idea is to give users easy-to-use endpoints to quickly query data from the BONSAI database but also seamlessly integrate LCA calculation routines in their own applications.

For example, using a Python interpreter:

import requests
r = requests.post('http://api.bonsai.uno/v1/do_lca/',
    json=
        {
            "uri": "http://rdf.bonsai.uno/activitytype/exiobase3_3_17/A_CMNT",
            "algorithm": "attributional",
            "unit": "kilogram",
            "amount": 1.0,
            "method": "CML 2001"
         }
    
    )
r.json()

would output:

    [
      {
        "label":"Manufacture of cement, lime and plaster",
        "uri":"http://rdf.bonsai.uno/activitytype/exiobase3_3_17/A_CMNT",
        "activityType":"",
        "algorithm": "attributional",
        "impacts": {
                "amount":650.8,
                "impact_name": "GWP100a",
                "unit": "kg CO2-eq."
            }
        }
    ]

We foresee bonsai_api to work together with:

• bonsai_app, (https://app.bonsai.uno) a server-based LCA calculation module that receives requests from bonsai_api,
• bonsai_UI, (https://ui.bonsai.uno) a web-based graphical user interface to request and visualize LCA calculations
• the BONSAI database

Install

Clone the repository

git clone https://github.com/BONSAMURAIS/bonsai_api

Create a virtual environment and activate it

python3 -m venv venv
. venv/bin/activate

Or on Windows cmd

py -3 -m venv venv
venv\Scripts\activate.bat

Install bonsai_api

pip install -e .

Or if you are using the master branch, install Flask from source before installing bonsai_web_api

pip install -e ../..
pip install -e .

Run

Docker

The docker image uses gunicorn to serve the application.

Build the image with:

docker build . -t bonsai_api

The minimal command line to run the image would look like:

docker run -p 5000:5000 bonsai_api

Running on another port (say, 8080) on the host, and displaying DEBUG logs from gunicorn:

docker run -e GUNICORN_CMD_ARGS="--log-level DEBUG" -p 8080:5000 bonsai_api

Running the application as a docker container and naming the container bonsai_api:

docker run -d --name bonsai_api -e GUNICORN_CMD_ARGS="--log-level DEBUG" -p 8080:5000 bonsai_api

To see the output logs from this conatiner:

docker logs bonsai_api

To follow the logs from the container (must do CTL-C to stop the logs from showing in the terminal, but the service will continue to run!)

docker logs -f bonsai_api

To stop the background service:

docker stop bonsai_api

Linux/MacOS

Set the environment variables

export FLASK_APP=bonsai_api
export FLASK_ENV=development

Run local server

flask run

Windows cmd

set FLASK_APP=bonsai_api
set FLASK_ENV=development
flask run

Open http://127.0.0.1:5000 in a browser.

Test

pip install '.[test]'
pytest -v

Run with coverage report

coverage run -m pytest
coverage report
coverage html  # open htmlcov/index.html in a browser