Folksonomy API

A lightweight REST API designed for the Open Food Facts Folksonomy Engine.

• Design documents: Folksonomy Engine Wiki
• API endpoint: https://api.folksonomy.openfoodfacts.org/
• Interactive API documentation: https://api.folksonomy.openfoodfacts.org/docs
• Browser extension to try it live: folksonomy_frontend GitHub
• Note: Moderators can access the folksonomy engine directly on Open Food Facts without any extension. The UI has not yet been deployed on Open Products Facts, Open Pet Food Facts, or Open Beauty Facts, but it has been proven to work via the extension.

Contributor's Guide

Check out our Contributor's Guide. Feel free to improve it or ask questions!

Dependencies

• Language: Python 3.x
• Framework: FastAPI
• Database: PostgreSQL

Development

You should create unit tests for each new feature or API change (see test_main.py).

To run tests, simply launch:

PYTHONASYNCIODEBUG=1 poetry run pytest tests/ folksonomy/

• The PYTHONASYNCIODEBUG=1 environment variable is important to ensure there are no pending asyncio tasks (a sign of potential issues).
• Warning: Running tests will wipe the database. Do not run tests in production.

Docker Setup

Using Docker is the easiest way to get started with the Folksonomy API. It requires minimal setup and ensures a consistent development environment.

Requirements

• Docker 17.06.0+
• Docker Compose 1.21.0+

Quick Start

1. Clone the repository:

   git clone https://github.com/openfoodfacts/folksonomy_api.git
   cd folksonomy_api

2. Copy the example settings file:

   cp local_settings_docker_example.py local_settings.py

3. Create an environment configuration file:

   cp .env.example .env

4. Eventually create the shared network (it might already exist if you develop with openfoodfacts-server)

   docker network create po_off_default

5. Start the services:

   docker compose up -d

6. Initialize the database (necessary on the first run or after migrations):

   docker compose run --rm folksonomy_api python db-migration.py

7. Access the API:

   • API: http://localhost:8000
   • Interactive docs: http://localhost:8000/docs

8. Stop the services:

   docker compose down

Development with Product Opener (Open Food Facts server)

If you want to test the integration with the Open Food Facts server, you just have to edit your .env to set:

AUTH_SERVER_STATIC=http://world.openfoodfacts.localhost

Then run your server and also run folksonomy_api.

Change your local openfoodfacts-server instance to use your local folksonomy_api instance, which is at folksonomy_api:8000. TODO: document how

Configuration

The Docker setup uses environment variables defined in docker-compose.yml. You can modify these as needed:

• POSTGRES_USER: Database username
• POSTGRES_PASSWORD: Database password
• POSTGRES_DATABASE: Database name
• POSTGRES_HOST: Database host (default: db)

Additional settings (such as authentication) can be configured in local_settings.py.

Note: The PostgreSQL service uses port 5433 to avoid conflicts with any local PostgreSQL installations.

Working with the Database

To connect to the PostgreSQL database inside the Docker container:

docker compose exec db psql -U folksonomy -d folksonomy

Traditional Setup

If you prefer installing everything directly on your machine (without Docker):

1. Install Python 3.9+
2. Install Poetry
3. Install PostgreSQL 13+
4. Follow the instructions in INSTALL.md to install the requirements and create a database user.
5. Copy local_settings_example.py and rename it to local_settings.py.
6. Update the parameters in local_settings.py as needed.
7. That's it!

Generating an OpenAPI Document

FastAPI uses OpenAPI (formerly Swagger) and JSON Schema.

You can generate the OpenAPI JSON document in two ways:

• Download it from https://api.folksonomy.openfoodfacts.org/openapi.json
• Or generate it locally:

./generate_openapi_json.py

If running inside Docker:

docker compose exec api python generate_openapi_json.py

Testing Product Opener integration (with docker)

To test with product opener, you just need to run the openfoodfacts-server project and the folksonomy_api project using docker compose.

If your on windows or mac, you also have to point the host api.folksonomy.openfoodfacts.localhost to 127.0.0.1 [^hosts file]

Thanks to the use a common_net (a common docker network), the openfoodfacts server will be able to communicate with the folksonomy_api docker, and the nginx frontend of openfoodfacts-server will act as a proxy to your folksonomy_api server (see conf/nginx-docker/nginx.conf).

After both projects are fully launched, you should be able to address http://api.folksonomy.openfoodfacts.localhost to access the folksonomy_api server (without using a specific port).

In case you are not sure about network names and so on, using docker inspect <containenr-name> and docker network inspect <network-name> can help you.

[^hosts file]: As administrator, edit the hosts file (Windows: C:\Windows\System32\drivers\etc\hosts; Linux/MacOSX: /etc/hosts), to add 127.0.0.1 api.folksonomy.openfoodfacts.localhost.

Normally, you already edit those file when you setup openfoodfacts-server

Code Style

This project uses Ruff for linting and code formatting.

• We recommend using pre-commit hooks for automatic linting, but it's optional (see install).
• See CONTRIBUTING.md for more details on code style and linting.

Deployment

Deployment information is available here: Open Food Facts - Folksonomy Deployment