GSOD2022 API documentation

Summary

Google Season Of Docs 2022 grant allow us to work on improving API Documentation

Lowering the API barrier to entry and developing API data contributions is main goal.

Description

Status

started

Expected outcomes

• Audit the existing documentation and create a friction log, especially around the API itself, and the tools used to maintain it.
• Improve  the Open Food Facts API based on feedback/exchanges with the community
• Extend the documentation with all the new routes and APIs listed in https://github.com/openfoodfacts/api-documentation
• Ensure all existing routes are compliant with best practices for OpenAPI that allow for SDK generation, testing…
• Participate in leveling up our API game and best practices, along with the core Open Food Facts team
• (stretch goal) Set up a GitHub Actions CI pipeline with mentors to convert the doc to Open API (and then to OpenAPI generated SDKs)

Impact

• make more people use the API, increasing database impact and contributions
• less needs for support to API users
• API documentation remains up to date and is tested
• more complete SDK can generated through Open-API tools

Timeline

(see also season of docs timeline)

• May 16: we announced selection of Funke as GSOD supported technical writer
• May 19: start of the project
• October 14th: end of the project

How to contribute

• Reporting your experience and frictions in using the API
• Reviewing documentation and contributing fixes
• Helping setup github actions and tooling to ensure documentation generation / testing

People

Project lead is Funke Olasupo.

Mentor is Alex-off

Resources / Contributing

Current API documentation : https://github.com/openfoodfacts/api-documentation/

Current postman to HTML tool : https://github.com/thedevsaddam/docgen/

Archives

• server code https://github.com/openfoodfacts/openfoodfacts-server