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.

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

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

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

To run tests, simply launch:

PYTHONASYNCIODEBUG=1 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.

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

• Docker 17.06.0+
• Docker Compose 1.21.0+

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. Start the services:

   docker compose up -d

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

   docker exec -it folksonomy_api-folksonomy_api-1 python db-migration.py

6. Access the API:

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

7. Stop the services:

   docker compose down

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.

To connect to the PostgreSQL database inside the Docker container:

docker compose exec db psql -U folksonomy -d folksonomy

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!

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

This project uses Ruff for linting and code formatting.

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

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