Difference between revisions of "GSOD2022 API documentation"
Jump to navigation
Jump to search
(added main informations) |
(+ Google announcement) |
||
| (5 intermediate revisions by 2 users not shown) | |||
| Line 2: | Line 2: | ||
[[SeasonOfDocs|Google Season Of Docs 2022]] grant allow us to work on improving API Documentation | [[SeasonOfDocs|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. | + | Lowering the API barrier to entry and developing API data contributions is the main goal. |
| + | |||
| + | See the [https://drive.google.com/drive/u/0/folders/1Zrjaq0_hP70d6NmMoFmlQvnMbNuwmd3w initial proposal]. | ||
===Description=== | ===Description=== | ||
| − | ==== | + | ==== Status==== |
started | started | ||
| − | ==== | + | ====Expected outcomes==== |
| − | * Audit the existing documentation and create a friction log, especially around the API itself, and the tools used to maintain it. | + | *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 | * 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 <nowiki>https://github.com/openfoodfacts/api-documentation</nowiki> | * Extend the documentation with all the new routes and APIs listed in <nowiki>https://github.com/openfoodfacts/api-documentation</nowiki> | ||
| − | * Ensure all existing routes are compliant with best practices for OpenAPI that allow for SDK generation, testing… | + | *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 | + | *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) | * (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 | + | *make more people use the API, increasing database impact and contributions |
* less needs for support to API users | * less needs for support to API users | ||
| − | * API documentation remains up to date and is tested | + | *API documentation remains up to date and is tested |
| − | * more complete SDK can generated through Open-API tools | + | *more complete SDK can generated through Open-API tools |
| − | ==== | + | ====Timeline==== |
(see also [https://developers.google.com/season-of-docs/docs/timeline season of docs timeline]) | (see also [https://developers.google.com/season-of-docs/docs/timeline season of docs timeline]) | ||
*May 16: we announced selection of Funke as GSOD supported technical writer | *May 16: we announced selection of Funke as GSOD supported technical writer | ||
| Line 31: | Line 33: | ||
*October 14th: end of the project | *October 14th: end of the project | ||
| − | ==== How to contribute ==== | + | ====How to contribute ==== |
| − | * Reporting your experience and frictions in using the API | + | *Reporting your experience and frictions in using the API |
| − | * Reviewing documentation and contributing fixes | + | *Reviewing documentation and contributing fixes |
| − | * Helping setup github actions and tooling to ensure documentation generation / testing | + | *Helping setup github actions and tooling to ensure documentation generation / testing |
| − | ==== People ==== | + | ====People==== |
Project lead is Funke Olasupo. | Project lead is Funke Olasupo. | ||
| Line 43: | Line 45: | ||
===Resources / Contributing=== | ===Resources / Contributing=== | ||
| + | Board: https://github.com/orgs/openfoodfacts/projects/27 | ||
| + | |||
| + | Weekly meeting : every wednesday at 11 CEST (9 UTC) - ask to join | ||
| + | |||
| + | Meetings minutes: https://docs.google.com/document/d/1nV_6U9a-sFa_BVlVFM9mSRNDjIfo0VWYOVHF9V_N4lo | ||
| + | |||
Current API documentation : https://github.com/openfoodfacts/api-documentation/ | Current API documentation : https://github.com/openfoodfacts/api-documentation/ | ||
| Line 49: | Line 57: | ||
===Archives=== | ===Archives=== | ||
| − | * server code https://github.com/openfoodfacts/openfoodfacts-server | + | *server code https://github.com/openfoodfacts/openfoodfacts-server |
| + | *Google [https://developers.google.com/season-of-docs/docs/participants announcement] of the GSOD 2022 participants (including Open Food Facts) | ||
* | * | ||
[[Category:Project]] | [[Category:Project]] | ||
Latest revision as of 14:23, 22 September 2022
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 the main goal.
See the initial proposal.
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
Board: https://github.com/orgs/openfoodfacts/projects/27
Weekly meeting : every wednesday at 11 CEST (9 UTC) - ask to join
Meetings minutes: https://docs.google.com/document/d/1nV_6U9a-sFa_BVlVFM9mSRNDjIfo0VWYOVHF9V_N4lo
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
- Google announcement of the GSOD 2022 participants (including Open Food Facts)