{"id":19670128,"url":"https://github.com/openfoodfacts/folksonomy_api","last_synced_at":"2025-09-06T22:34:17.567Z","repository":{"id":38094171,"uuid":"358820127","full_name":"openfoodfacts/folksonomy_api","owner":"openfoodfacts","description":"A light REST API designed for Open Food Facts folksonomy engine","archived":false,"fork":false,"pushed_at":"2025-08-14T15:57:16.000Z","size":484,"stargazers_count":21,"open_issues_count":39,"forks_count":33,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-08-21T00:34:10.409Z","etag":null,"topics":["fastapi","folksonomy-engine","hacktoberfest","openapi","openfoodfacts","python","swagger"],"latest_commit_sha":null,"homepage":"https://wiki.openfoodfacts.org/Folksonomy_Engine","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openfoodfacts.png","metadata":{"funding":{"patreon":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"open_collective":"openfoodfacts-server","github":"openfoodfacts","custom":"https://donate.openfoodfacts.org"},"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-04-17T08:02:17.000Z","updated_at":"2025-08-13T13:49:02.000Z","dependencies_parsed_at":"2023-02-17T05:16:04.807Z","dependency_job_id":"c3a4247b-4a1f-4876-bed6-477615f477c3","html_url":"https://github.com/openfoodfacts/folksonomy_api","commit_stats":{"total_commits":170,"total_committers":10,"mean_commits":17.0,"dds":0.6176470588235294,"last_synced_commit":"556339e4b3f9c7ccb73a668f3a1407bbb7bac4e3"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/openfoodfacts/folksonomy_api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openfoodfacts%2Ffolksonomy_api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openfoodfacts%2Ffolksonomy_api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openfoodfacts%2Ffolksonomy_api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openfoodfacts%2Ffolksonomy_api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openfoodfacts","download_url":"https://codeload.github.com/openfoodfacts/folksonomy_api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openfoodfacts%2Ffolksonomy_api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273973696,"owners_count":25200575,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-06T02:00:13.247Z","response_time":2576,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","folksonomy-engine","hacktoberfest","openapi","openfoodfacts","python","swagger"],"created_at":"2024-11-11T17:04:19.684Z","updated_at":"2025-09-06T22:34:17.558Z","avatar_url":"https://github.com/openfoodfacts.png","language":"Python","funding_links":["https://opencollective.com/openfoodfacts-server","https://github.com/sponsors/openfoodfacts","https://donate.openfoodfacts.org"],"categories":["Agriculture and Food Safety"],"sub_categories":[],"readme":"# Folksonomy API\n\nA lightweight REST API designed for the Open Food Facts Folksonomy Engine.\n\n- **Design documents**: [Folksonomy Engine Wiki](https://wiki.openfoodfacts.org/Folksonomy_Engine)\n- **API endpoint**: [https://api.folksonomy.openfoodfacts.org/](https://api.folksonomy.openfoodfacts.org/)\n- **Interactive API documentation**: [https://api.folksonomy.openfoodfacts.org/docs](https://api.folksonomy.openfoodfacts.org/docs)\n- **Browser extension to try it live**: [folksonomy_frontend GitHub](https://github.com/openfoodfacts/folksonomy_frontend)\n- **Note**: Moderators can access the folksonomy engine directly on Open Food Facts without any extension.\n  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.\n\n# Contributor's Guide\n\nCheck out our [Contributor's Guide](./CONTRIBUTING.md).\nFeel free to improve it or ask questions!\n\n# Dependencies\n\n- **Language**: Python 3.x\n- **Framework**: [FastAPI](https://fastapi.tiangolo.com/)\n- **Database**: PostgreSQL\n\n# Development\n\nYou should create unit tests for each new feature or API change (see [test_main.py](https://github.com/openfoodfacts/folksonomy_api/blob/main/tests/test_main.py)).\n\nTo run tests, simply launch:\n\n```bash\nPYTHONASYNCIODEBUG=1 poetry run pytest tests/ folksonomy/\n```\n\n- The `PYTHONASYNCIODEBUG=1` environment variable is important to ensure there are no pending asyncio tasks (a sign of potential issues).\n- **Warning**: Running tests will wipe the database. **Do not run tests in production.**\n\n# Docker Setup\n\nUsing Docker is the easiest way to get started with the Folksonomy API.\nIt requires minimal setup and ensures a consistent development environment.\n\n## Requirements\n\n- Docker 17.06.0+\n- Docker Compose 1.21.0+\n\n## Quick Start\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/openfoodfacts/folksonomy_api.git\n   cd folksonomy_api\n   ```\n\n2. Copy the example settings file:\n   ```bash\n   cp local_settings_docker_example.py local_settings.py\n   ```\n\n3. Create an environment configuration file:\n   ```bash\n   cp .env.example .env\n   ```\n\n3. Eventually create the shared network (it might already exist if you develop with [openfoodfacts-server](https://github.com/openfoodfacts/openfoodfacts-server/pulls))\n   ```bash\n   docker network create po_off_default\n   ```\n\n4. Start the services:\n   ```bash\n   docker compose up -d\n   ```\n\n5. Initialize the database (necessary on the first run or after migrations):\n   ```bash\n   docker compose run --rm folksonomy_api python db-migration.py\n   ```\n\n6. Access the API:\n   - API: [http://localhost:8000](http://localhost:8000)\n   - Interactive docs: [http://localhost:8000/docs](http://localhost:8000/docs)\n\n7. Stop the services:\n   ```bash\n   docker compose down\n   ```\n\n### Development with Product Opener (Open Food Facts server)\n\nIf you want to test the integration with the Open Food Facts server,\nyou just have to edit your .env to set:\n```conf\nAUTH_SERVER_STATIC=http://world.openfoodfacts.localhost\n```\nThen run your server and also run folksonomy_api.\n\nChange your local openfoodfacts-server instance to use your local folksonomy_api instance, which is at folksonomy_api:8000.\n**TODO:** document how\n\n## Configuration\n\nThe Docker setup uses environment variables defined in `docker-compose.yml`.\nYou can modify these as needed:\n\n- `POSTGRES_USER`: Database username\n- `POSTGRES_PASSWORD`: Database password\n- `POSTGRES_DATABASE`: Database name\n- `POSTGRES_HOST`: Database host (default: `db`)\n\nAdditional settings (such as authentication) can be configured in `local_settings.py`.\n\n**Note**: The PostgreSQL service uses port `5433` to avoid conflicts with any local PostgreSQL installations.\n\n## Working with the Database\n\nTo connect to the PostgreSQL database inside the Docker container:\n\n```bash\ndocker compose exec db psql -U folksonomy -d folksonomy\n```\n\n# Traditional Setup\n\nIf you prefer installing everything directly on your machine (without Docker):\n\n1. Install Python 3.9+\n2. Install Poetry\n3. Install PostgreSQL 13+\n4. Follow the instructions in [INSTALL.md](https://github.com/openfoodfacts/folksonomy_api/blob/main/INSTALL.md) to install the requirements and create a database user.\n5. Copy [local_settings_example.py](https://github.com/openfoodfacts/folksonomy_api/blob/main/local_settings_example.py) and rename it to `local_settings.py`.\n6. Update the parameters in `local_settings.py` as needed.\n7. That's it!\n\n# Generating an OpenAPI Document\n\nFastAPI uses [OpenAPI](https://github.com/OAI/OpenAPI-Specification) (formerly Swagger) and [JSON Schema](https://json-schema.org/).\n\nYou can generate the OpenAPI JSON document in two ways:\n\n- Download it from [https://api.folksonomy.openfoodfacts.org/openapi.json](https://api.folksonomy.openfoodfacts.org/openapi.json)\n- Or generate it locally:\n\n```bash\n./generate_openapi_json.py\n```\n\nIf running inside Docker:\n\n```bash\ndocker compose exec api python generate_openapi_json.py\n```\n\n## Testing Product Opener integration (with docker)\n\nTo test with product opener, you just need to run the [openfoodfacts-server project]() and the folksonomy_api project using docker compose.\n\nIf your on windows or mac, you also have to point the host api.folksonomy.openfoodfacts.localhost to 127.0.0.1 [^hosts file]\n\nThanks to the use a common_net (a common docker network),\nthe openfoodfacts server will be able to communicate with the folksonomy_api docker,\nand the nginx frontend of openfoodfacts-server will act as a proxy to your folksonomy_api server\n(see `conf/nginx-docker/nginx.conf`).\n\nAfter both projects are fully launched,\nyou should be able to address http://api.folksonomy.openfoodfacts.localhost\nto access the folksonomy_api server (without using a specific port).\n\nIn case you are not sure about network names and so on,\nusing `docker inspect \u003ccontainenr-name\u003e` and\n`docker network inspect \u003cnetwork-name\u003e` can help you.\n\n[^hosts file]: As administrator, edit the hosts file (Windows: C:\\Windows\\System32\\drivers\\etc\\hosts; Linux/MacOSX: /etc/hosts),\n  to add `127.0.0.1 api.folksonomy.openfoodfacts.localhost`.\n\n  Normally, you already edit those file [when you setup openfoodfacts-server](https://openfoodfacts.github.io/openfoodfacts-server/dev/how-to-quick-start-guide/#3-build-your-dev-environment)\n\n# Code Style\n\nThis project uses [Ruff](https://github.com/astral-sh/ruff) for linting and code formatting.\n\n- We recommend using pre-commit hooks for automatic linting, but it's optional (see [install](https://pre-commit.com/#install)).\n- See [CONTRIBUTING.md](CONTRIBUTING.md) for more details on code style and linting.\n\n\n# Deployment\n\nDeployment information is available here:\n[Open Food Facts - Folksonomy Deployment](https://openfoodfacts.github.io/openfoodfacts-infrastructure/folksonomy/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenfoodfacts%2Ffolksonomy_api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenfoodfacts%2Ffolksonomy_api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenfoodfacts%2Ffolksonomy_api/lists"}