Skip to content

Latest commit

 

History

History
173 lines (107 loc) · 4.92 KB

README.md

File metadata and controls

173 lines (107 loc) · 4.92 KB
Raw

BoaviztAPI

An API to access Boavizta's methodologies and data

See the documentation for API usage and methodology.

Python tests

💬 Join us on our public chat

🎯 Objective

Boavizta aims to enhance the assessment of environmental impacts induced by ICTs in organizations by providing widespread access to our work in an automated and efficient manner.

Boavizta integrates various data and methodologies, which are combined and made accessible through this API.

Transparency and the popularization of scientific knowledge are of utmost importance in this project, and key aspects include open-sourcing the code, versioning the impact factors, and thoroughly documenting the project.

In the interest of transparency and scientific popularization, the opening of the code, the versioning of the impact factors and the documentation of the project are critical points.

The system follows a bottom-up approach in its development, organized into layers. The initial layer focuses on equipment. The second layer focues on the impacts of digital services (e.g. cloud instances) or systems. However, assessing the overall global impact of ICT is currently beyond the project's scope.

⏩ Test it yourself (no installation)

Run a local instance

🐳 Run API using docker

$ docker run -p 5000:5000 ghcr.io/boavizta/boaviztapi:latest

Access API at http://localhost:5000

Install using pip package

$ pip3 install boaviztapi

Then you can run the server locally with :

$ uvicorn boaviztapi.main:app --host=localhost --port 5000

💻 Development

Prerequisite

Python 3 mandatory, python >=3.9 recommended, poetry recommended

Setup poetry

Install poetry.

$ pip3 install poetry

Install dependencies and create a python virtual environment.

$ make install
$ poetry shell

Launch a development server

Once in the poetry environment

Development server uses uvicorn and fastapi, you can launch development server with the uvicorn CLI.

$ uvicorn boaviztapi.main:app --host=localhost --port 5000

You can run the tests with pytest.

Create your own docker image and run it

Build application package

make install

Build docker image

# using the makefile (recommended)
make docker-build

# manual build (requires to set version)
docker build --build-arg VERSION=`poetry version -s` .

Run docker image

docker run -p 5000:5000/tcp boavizta/boaviztapi:latest

Alternative (if you don't have Python or Poetry)

make docker-build-development

Deploy to AWS as serverless application

⚠ This is currently not working , see Deployment as serverless application does not work · Issue #153 · Boavizta/boaviztapi

Api can be self hosted to your own AWS account using the serverless framework.

# Install the serverless framework and plugins
npm install -g serverless
npm i
# Authenticate
export AWS_PROFILE=your-own-profile
# Deploy to dev
serverless deploy

Fisrt packaging/deployment may takes a several minutes

OpenAPI specification (Swagger)

Once API server is launched API swagger is available at httsp://localhost:5000/docs.

👩 Contributing

See contributing.md

You can build a source distribution (installable with pip) with make build.

1️⃣ Versioning

We use Semantic Versioning 2.0.0

Type Description Command
MAJOR version when you make incompatible API changes make major
MINOR version when you add functionality in a backwards compatible manner make minor
PATCH version when you make backwards compatible bug fixes make patch

2️⃣ Publishing

You can run :

API_TOKEN=<your_token> make distribute

📜 License

GNU Affero General Public License v3.0