├── Final Product Report.pdf ├── Translation Guidelines.pdf ├── SUMMARY.md ├── files └── images │ └── smack-tastic.jpg ├── .github ├── dependabot.yml ├── CODEOWNERS └── workflows │ ├── auto-assign-pr.yml │ ├── release-please.yml │ ├── semantic-pr.yml │ ├── github-projects.yml │ └── postman.yml ├── REUSE.md ├── off-net-env.json ├── off-org-env.json ├── README.md └── friction-log └── README.md /Final Product Report.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openfoodfacts/api-documentation/HEAD/Final Product Report.pdf -------------------------------------------------------------------------------- /Translation Guidelines.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openfoodfacts/api-documentation/HEAD/Translation Guidelines.pdf -------------------------------------------------------------------------------- /SUMMARY.md: -------------------------------------------------------------------------------- 1 | # Table of contents 2 | 3 | * [README](README.md) 4 | * [API Documentation Friction Log](friction-log/README.md) 5 | -------------------------------------------------------------------------------- /files/images/smack-tastic.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/openfoodfacts/api-documentation/HEAD/files/images/smack-tastic.jpg -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | 4 | - package-ecosystem: "github-actions" 5 | directory: "/" 6 | schedule: 7 | interval: "daily" 8 | commit-message: 9 | prefix: "chore" 10 | include: "scope" 11 | -------------------------------------------------------------------------------- /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | 2 | # These owners will be the default owners for everything in 3 | # the repo. Unless a later match takes precedence, 4 | # review when someone opens a pull request. 5 | # For more on how to customize the CODEOWNERS file - https://help.github.com/en/articles/about-code-owners 6 | 7 | * @openfoodfacts/api-documentation 8 | -------------------------------------------------------------------------------- /.github/workflows/auto-assign-pr.yml: -------------------------------------------------------------------------------- 1 | # .github/workflows/auto-author-assign.yml 2 | name: 'Auto Author Assign' 3 | 4 | on: 5 | pull_request_target: 6 | types: [opened, reopened] 7 | 8 | permissions: 9 | pull-requests: write 10 | 11 | jobs: 12 | assign-author: 13 | runs-on: ubuntu-latest 14 | steps: 15 | - uses: toshimaru/auto-author-assign@v2.1.1 16 | -------------------------------------------------------------------------------- /.github/workflows/release-please.yml: -------------------------------------------------------------------------------- 1 | name: Run release-please 2 | on: 3 | push: 4 | branches: 5 | - develop 6 | jobs: 7 | release-please: 8 | runs-on: ubuntu-latest 9 | steps: 10 | - uses: GoogleCloudPlatform/release-please-action@v3 11 | with: 12 | token: ${{ secrets.GITHUB_TOKEN }} 13 | release-type: simple 14 | -------------------------------------------------------------------------------- /.github/workflows/semantic-pr.yml: -------------------------------------------------------------------------------- 1 | name: "Semantic PRs" 2 | 3 | on: 4 | pull_request_target: 5 | types: 6 | - opened 7 | - edited 8 | - synchronize 9 | 10 | jobs: 11 | main: 12 | name: Validate PR title 13 | runs-on: ubuntu-latest 14 | steps: 15 | - uses: amannn/action-semantic-pull-request@v5 16 | env: 17 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 18 | -------------------------------------------------------------------------------- /REUSE.md: -------------------------------------------------------------------------------- 1 | ## If you'd like to add your app: 2 | * Please log your reuse on this form 3 | * You can also list your project on Data.gouv.fr 4 | 5 | ## Applications using our Dart SDK 6 | * https://github.com/openfoodfacts/openfoodfacts-dart/blob/master/README.md#applications-using-this-sdk 7 | 8 | -------------------------------------------------------------------------------- /off-net-env.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "off-net", 3 | "values": [{ 4 | "key": "DOMAIN_NAME", 5 | "value": "openfoodfacts.net", 6 | "enabled": true 7 | }, 8 | { 9 | "key": "PRODUCT_NUMBER", 10 | "value": "04963406", 11 | "enabled": true 12 | }, 13 | { 14 | "key": "PROTOCOL", 15 | "value": "https", 16 | "enabled": true 17 | }, 18 | { 19 | "key": "API_VERSION", 20 | "value": "2", 21 | "enabled": true 22 | } 23 | ], 24 | "_postman_variable_scope": "environment", 25 | "_postman_exported_at": "2021-08-27T09:11:37.293Z", 26 | "_postman_exported_using": "Postman/8.10.0" 27 | } 28 | -------------------------------------------------------------------------------- /off-org-env.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "off-net", 3 | "values": [{ 4 | "key": "DOMAIN_NAME", 5 | "value": "openfoodfacts.org", 6 | "enabled": true 7 | }, 8 | { 9 | "key": "PRODUCT_NUMBER", 10 | "value": "04963406", 11 | "enabled": true 12 | }, 13 | { 14 | "key": "PROTOCOL", 15 | "value": "https", 16 | "enabled": true 17 | }, 18 | { 19 | "key": "API_VERSION", 20 | "value": "2", 21 | "enabled": true 22 | } 23 | ], 24 | "_postman_variable_scope": "environment", 25 | "_postman_exported_at": "2021-08-27T09:11:37.293Z", 26 | "_postman_exported_using": "Postman/8.10.0" 27 | } 28 | -------------------------------------------------------------------------------- /.github/workflows/github-projects.yml: -------------------------------------------------------------------------------- 1 | name: Add bugs to the Documentation GitHub Project 2 | 3 | on: 4 | issues: 5 | types: 6 | - opened 7 | pull_request: 8 | types: 9 | - opened 10 | jobs: 11 | add-to-project: 12 | name: Add issue to project 13 | runs-on: ubuntu-latest 14 | if: github.event.pull_request.head.repo.full_name == github.repository 15 | steps: 16 | - uses: actions/add-to-project@main 17 | with: 18 | project-url: https://github.com/orgs/openfoodfacts/projects/25 19 | github-token: ${{ secrets.ADD_TO_PROJECT_PAT }} 20 | label-operator: AND 21 | -------------------------------------------------------------------------------- /.github/workflows/postman.yml: -------------------------------------------------------------------------------- 1 | name: Build and test Postman collection 2 | 3 | on: 4 | push: 5 | branches: 6 | - develop 7 | pull_request: 8 | 9 | jobs: 10 | build: 11 | name: Build documentation 12 | runs-on: ubuntu-18.04 13 | steps: 14 | - name: Set deploy env 15 | run: | 16 | echo "off_env=${{ github.ref == 'refs/heads/develop' && 'off-org' || 'off-net'}}" >> $GITHUB_ENV 17 | 18 | - name: Checkout 19 | uses: actions/checkout@v4 20 | 21 | - name: Install docgen 22 | run: curl https://raw.githubusercontent.com/thedevsaddam/docgen/v3/install.sh -o install.sh && chmod +x install.sh && ./install.sh && rm install.sh 23 | 24 | - name: Generate HTML documentation 25 | run: docgen build -i off-pm-collection.json -e ${{ env.off_env }}-env.json -o index.html 26 | 27 | # TODO: Debug this as it hangs 28 | # - name: Generate Markdown documentation 29 | # run: docgen build -i off-pm-collection.json -e off-pm-env.json -o index.md -m 30 | 31 | - name: Commit generated documentation to current branch 32 | uses: stefanzweifel/git-auto-commit-action@v4 33 | with: 34 | repository: . 35 | file_pattern: index.* 36 | commit_message: Commit docgen-generated docs 37 | commit_options: '--no-verify --signoff' 38 | 39 | - name: Deploy HTML docs to Github Pages [STAGING] 40 | uses: JamesIves/github-pages-deploy-action@v4.7.3 41 | if: ${{ startsWith(github.ref, 'refs/pull') }} 42 | with: 43 | token: ${{ secrets.CROSS_REPO_TOKEN }} 44 | branch: gh-pages # <- Branch on which commit will be made 45 | repository-name: openfoodfacts/api-documentation-staging 46 | folder: . # <- Folder containing our generated HTML docs 47 | 48 | - name: Add comment to PR 49 | uses: thollander/actions-comment-pull-request@v2.4.0 50 | if: ${{ startsWith(github.ref, 'refs/pull') }} 51 | with: 52 | message: Staging documentation deployed to https://openfoodfacts.github.io/api-documentation-staging 53 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 54 | 55 | - name: Deploy HTML docs to Github Pages [PROD] 56 | uses: JamesIves/github-pages-deploy-action@v4.7.3 57 | if: ${{ github.ref == 'refs/heads/master' }} 58 | with: 59 | token: ${{ secrets.GITHUB_TOKEN }} 60 | branch: gh-pages # <- Branch on which commit will be made 61 | folder: . # <- Folder containing our generated HTML docs 62 | 63 | test: 64 | name: Run API integration tests 65 | runs-on: ubuntu-18.04 66 | steps: 67 | - name: Set deploy env 68 | run: | 69 | echo "off_env=${{ github.ref == 'refs/heads/master' && 'off-org' || 'off-net'}}" >> $GITHUB_ENV 70 | - name: Checkout 71 | uses: actions/checkout@v4 72 | - name: Run API Tests 73 | id: run-newman 74 | uses: anthonyvscode/newman-action@v1 75 | with: 76 | collection: off-pm-collection.json 77 | environment: ${{ env.off_env }}-env.json 78 | reporters: cli 79 | - name: Output summary to console 80 | run: echo ${{ steps.run-newman.outputs.summary }} 81 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # API Documentation 2 | 3 | ## Deprecation notice 4 | 5 | **Important**: 6 | This documentation is being deprecated in favour of the new OpenAPI documentation (see below) 7 | 8 | ## Up-to-date Documentation of the Open Food Facts API 9 | 10 | * intro: https://openfoodfacts.github.io/openfoodfacts-server/api/ 11 | * OpenAPI source: https://github.com/openfoodfacts/openfoodfacts-server/tree/main/docs/api/ref 12 | 13 | # Archive 14 | 15 | ## Rendering of this (deprecated) documentation 16 | 17 | The API documentation is rendered here (see above for the more up-to-date documentation): 18 | 19 | * Stable version of the doc: https://openfoodfacts.github.io/api-documentation/ 20 | * Staging version of the doc: https://openfoodfacts.github.io/api-documentation-staging/ 21 | 22 | We have an older version available on the Wiki. 23 | 24 | * https://wiki.openfoodfacts.org/Documentation 25 | 26 | ## Roadmap 27 | 28 | We need documentation maintainers 29 | 30 | * [ ] to document new features (Eco-Score, Attributes…) 31 | * [ ] to improve existing documents based on feedback and questions in the #api channel 32 | * [ ] What can I help with ? https://github.com/openfoodfacts/api-documentation/issues/23 33 | 34 | ## Edit this (deprecated) documentation 35 | 36 | Remember that this project is deprecated, you should instead contribute to the OpenAPI documentation. 37 | 38 | ### Install the Postman application 39 | 40 | https://www.postman.com/downloads/ 41 | 42 | ### Clone the repository 43 | 44 | ``` 45 | git clone https://github.com/openfoodfacts/api-documentation 46 | git checkout -b 47 | ``` 48 | 49 | ### Edit the collection with Postman 50 | 51 | * Open Postman 52 | * Click "Import" then "Folder" and browse to this repository's folder. 53 | * Postman collection and environment located in the repo will be imported in your Postman application. 54 | * Edit the collection using the application, and once you're done click "Export" 55 | * Rename the file as `off-pm-collection.json` 56 | * Save it (overwrite the original one) 57 | 58 | ### Push to git 59 | 60 | Now it's time to propose your changes as a pull request on the repository. We're going to make a branch and commit our updated `off-pm-collection.json`. 61 | 62 | Run: 63 | 64 | ``` 65 | git checkout -b 66 | git add off-pm-collection.json 67 | git commit -m ""` 68 | git push --set-upstream origin 69 | ``` 70 | 71 | Once you are done: 72 | 73 | * Open a browser 74 | * Navigate to https://github.com/openfoodfacts/api-documentation 75 | * Open a new PR from your branch ("Create Pull Request" button). 76 | * View your updated documentation that was automatically deployed to the staging environment https://openfoodfacts.github.io/api-documentation-staging. 77 | 78 | 79 | ## Applications using this API 80 | 81 | ### Official application 82 | 83 | The official Open Food Facts app uses the API. 84 | 85 | ### Third party applications 86 | 87 | Feel free to open a PR to add your application in this list. 88 | 89 | - **Gluten Scan**. [Android](https://play.google.com/store/apps/details?id=com.healthyfood.gluten_free_app) / [iOS](https://apps.apple.com/ch/app/gluten-scanner/id1540660083) 90 | - **Halal & Healthy**. [Android](https://play.google.com/store/apps/details?id=com.TagIn.Tech.handh) / [iOS](https://apps.apple.com/ch/app/halal-healthy/id1603051382) 91 | - **Fitness Tracker**. [Android](https://play.google.com/store/apps/details?id=dk.cepk.fitness_tracker) 92 | -------------------------------------------------------------------------------- /friction-log/README.md: -------------------------------------------------------------------------------- 1 | # API Documentation Friction Log 2 | 3 | This log lists all the glitches that makes the [Open Food Facts API documentation](https://openfoodfacts.github.io/api-documentation/) hard to use, but frames it around a narrative use case. Each log item can be created as issues so thier progress can be tracked. 4 | 5 | ## User Friction 6 | 7 | These are frictions of [Open Food Facts API documentation](https://openfoodfacts.github.io/api-documentation/) framed around a customer(user) use case. 8 | 9 | Title | Description 10 | ------------------------| --------- 11 | | Filter products based on countries| Do you use countries or countries_tag ? (Properly indicate in the next doc) 12 | | JSON response| The fields returned in a response are not properly described. For example it turns out that _nutriments.unit_ and _nutriments.value_ does not mean anything. Can the [READ Request](https://openfoodfacts.github.io/api-documentation/#collapse-2READrequests-Getnutritionfactsforaspecificbarcode) response length be reviewed? This is because the response is too lengthy and so many information can be lost in the crowd. 13 | |Contribution guidelines | A more detailed and easily understandable guideline for open source enthusiasts to easily contribute to the current documentation. 14 | |FAQ | [The link is broken](https://openfoodfacts.github.io/api-documentation/#9FAQ) and it should be more visible. A survey can be done for the development team to get more FAQ with detailed answers. The texts in the FAQ’s do not match up with the rest of the documentation. FAQ’s should also be updated with more questions as the API keeps improving its version. 15 | |Taxonomy Unit| Remove _unit_ and _value_ from value in returned fields because they cprrespond to each other and they are for internal purposes. 16 | |Add image to existing product | Improved the guidelines on how to add photo to an existing product irrespective of file type etc. 17 | |Tutorials | Create real-life sample tutorials on how to build with the Open Food Facts database (either articles or video tutorials) 18 | |Glossary | Build a glossary for all technical terms in this project 19 | |Visibility | The documentation isnt easy to see , at least it should be visible in the project landing page and github . 20 | |Navigation | Current documentation is overcrowded and difficult to navigate. The side navbar section does not stay in the same place when the user scrolls down, this makes the docs harder to use since the user has to scroll upwards again to find new information within the docs. 21 | |Authentication | Do we need to authenticate at any point when using this API? If yes, indicate properly. 22 | |Version |3 different versions of the documentation, but no authoritative version (wiki (obsolete, should be deleted), api-documentation (more up to date but not complete), Postman cloud (obsolete). 23 | |Broswer compatibility | It does not display in firefox 24 | |News & Updates | A News & Updates section where users are informed of the updates that have been made to the documentation. 25 | |Local Machine Server | Include the [local deployment server url](http://world.openfoodfacts.localhost/) to the Open API file and explain its use case. We may have a developers note section for things that developers should take not of . for example this. 26 | |How to contribute to the Open API file | If changes were to be made to the open api spec file , add a guideline to help people know a few things about the open api file and how to contribute to it. 27 | 28 | ## Future Proposals 29 | 30 | After the new documention shipped its first phase, these plans can be looked at to improve community contributions. 31 | 32 | ### Proper contributor follow-up and community check-in 33 | 34 | Create good first issues, do follow ups on contributors for these issues and keep improving contributors guideline. Schedule weekly/biweekly contributors meet/newcomers call so new contributors can habe a great headstart with contributing to the project. 35 | 36 | ## Developer Friction 37 | 38 | These are frictions of [Open Food Facts API documentation](https://openfoodfacts.github.io/api-documentation/) framed around a developer/documentation contributor use case. 39 | 40 | Title | Description 41 | ------------------------| ---------- 42 | |Proximity | The documentation isn't close to the code 43 | |Review | Changes should be reviewable via Github Pull Requests 44 | |Test | Run tests on the proposed changes in the documentation before any merge is made to the main documentation. 45 | 46 | ## API Friction Log 47 | 48 | During the survey , some frictions were discovered that resulted from the API itself. They are key things for the developers to look out while building the next API version. 49 | 50 | Title | Description 51 | ------------------------| --------- 52 | |Search| Current API: not being able to do a precise search on product name. E.g _The database result are working fine for normal products like “Milk” but when I try to query for a fruit or vegetable like “Apple” the results always show me products like “Apple juice”, “Apple rings” instead of the actual product I'm searching for which is an Apple._ 53 | |Add image to existing product | In a future version of the API, having a field name for the image that does not change depending on the image type or language. 54 | 55 | 56 | --------------------------------------------------------------------------------