Line 1: |
Line 1: |
| [[Category:Developer]] [[Category:API]] | | [[Category:Developer]] [[Category:API]] |
| + | The API (Application Programming Interface) is the way an application can enter in dialogue with Open Food Facts application server. |
| + | |
| + | It can be used to retrieve data (search), read or write information (see disclaimer, in production, this should correspond to a user scan). |
| + | |
| + | ⚠ '''Disclaimer''': |
| + | |
| + | If you are not in a production scenario, think about using the pre-production instance at https://world.openfoodfacts.net. |
| + | |
| + | If you want to use data from open food facts for research, for heavy duty, or to get performance insurance, you may duplicate the database: see https://world.openfoodfacts.org/data |
| + | |
| + | == Search API v2 == |
| + | A new search api (work in progress) is available, which is easier to use. See [[Open Food Facts Search API Version 2]] |
| + | |
| + | = NEW version of the documentation = |
| + | |
| + | The new version of the documentation is available here: |
| + | * [https://openfoodfacts.github.io/api-documentation Latest version of the documentation] |
| + | |
| + | We have many SDKs at the bottom of the page, and we also have official implementations for Android, iPhone (and Flutter) that you can draw inspiration from. |
| + | |
| + | = Previous version of the documentation = |
| | | |
− | == Introduction ==
| |
| === Notice for API users === | | === Notice for API users === |
− | # You are very welcome to use the API for production cases, as long as 1 API call = 1 real scan by a user. | + | # You are very welcome to use the API for production cases, as long as '''1 API call = 1 real scan by a user'''. |
| # <span style="color:#d33">'''If you need all the database, download it directly from the data page, do ''NOT'' scrape the API'''</span> | | # <span style="color:#d33">'''If you need all the database, download it directly from the data page, do ''NOT'' scrape the API'''</span> |
| # Please tell us (contact@openfoodfacts.org or in the #API channel) what you build with the API, it's always great to see new reuses come to life :-) | | # Please tell us (contact@openfoodfacts.org or in the #API channel) what you build with the API, it's always great to see new reuses come to life :-) |
Line 33: |
Line 53: |
| * You can do READ operations using the production server. | | * You can do READ operations using the production server. |
| * You should use the SSL version of the API. <code>https://world.openfoodfacts.org</code> | | * You should use the SSL version of the API. <code>https://world.openfoodfacts.org</code> |
− | * '''Please send a UserAgent HTTP Header''' with the name of the app/service querying, the version, system and a URL if you have one, so that you are not blocked by mistake (e.g. <code>UserAgent: CoolFoodApp - Android - Version 1.0 - https://coolfoodapp.com</code>) | + | * '''Please send a UserAgent HTTP Header''' with the name of the app/service querying, the version, system and a URL if you have one, so that you are not blocked by mistake (e.g. <code>UserAgent: MyFoodApp - Android - Version 1.0 - https://myfoodapp.example.com</code>) |
| | | |
| == WRITE operations == | | == WRITE operations == |
Line 45: |
Line 65: |
| | | |
| === A few things === | | === A few things === |
− | * '''Do''' join the API channel if you intend on using WRITE | + | * '''DO''' join the API channel if you intend on using WRITE |
− | * '''Do not''' send copyrighted photos or information using the API. Everything you send is OdBL for the data, and CC-BY-SA for the pictures. If those are not yours (eg from scraping), you bear all the legal consequences. | + | * '''DO NOT''' send copyrighted photos or information using the API. Everything you send is OdBL for the data, and CC-BY-SA for the pictures. If those are not yours (eg from scraping), you bear all the legal consequences. |
| * You can create a global account for your app if you don't want to implement Open Food Facts user creation in your app right now. Please report it in #api so that it can be monitored for errors. | | * You can create a global account for your app if you don't want to implement Open Food Facts user creation in your app right now. Please report it in #api so that it can be monitored for errors. |
| * You should do all your test edits on https://world.openfoodfacts.dev (ask for the password on Slack) | | * You should do all your test edits on https://world.openfoodfacts.dev (ask for the password on Slack) |
Line 56: |
Line 76: |
| * fields that end with a language 2 letter code (e.g. fr for French) is the set of tags in that language | | * fields that end with a language 2 letter code (e.g. fr for French) is the set of tags in that language |
| * fields that end with _100g correspond to the amount of a nutriment (in g) for 100 g or 100 ml of product | | * fields that end with _100g correspond to the amount of a nutriment (in g) for 100 g or 100 ml of product |
| + | * keys must match BSON syntax, and may not contain `.` or `$`. |
| | | |
| === Ready made code you can use in your app === | | === Ready made code you can use in your app === |
Line 61: |
Line 82: |
| | | |
| == SDKs == | | == SDKs == |
− | We have projects to create SDKs for major platforms. If you'd like to help out, please join the dedicated Slack channels. | + | We have projects to create SDKs for major platforms. If you'd like to help out, [https://slack.openfoodfacts.org please join the dedicated Slack discussion channels] or open an issue on the existing repository. |
− | * [[API/Android|Android SDK]] | + | |
− | * [[API/C sharp|C# SDK]] - https://github.com/Albert-Le5/openfoodfacts-csharp ; https://github.com/aberteau/OpenFoodFacts4Net | + | It is important that SDK support both read and write operations, and evolve with the API. |
| + | |
| + | * [[API/Android|Android SDK]] - The official app used to be coded in Java and is now in Kotlin. Extraction into a reusable library would be welcome. |
| + | * C# SDK - https://github.com/Albert-Le5/openfoodfacts-csharp ; https://github.com/aberteau/OpenFoodFacts4Net |
| * [[API/Go|Go SDK]] - https://github.com/openfoodfacts/openfoodfacts-go | | * [[API/Go|Go SDK]] - https://github.com/openfoodfacts/openfoodfacts-go |
− | * [[API/Java|Java SDK]] | + | * [[API/Java|Java SDK]] - https://github.com/openfoodfacts/openfoodfacts-java |
− | * [[API/Javascript|JavaScript SDK]] | + | * [[API/Javascript|JavaScript SDK]] - We don't have a vanilla Javascript SDK right now |
− | * [[API/Javascript/NodeJS|NodeJS SDK]] | + | * Dart - https://github.com/openfoodfacts/openfoodfacts-dart |
− | * [[API/Perl|Perl SDK]]
| + | * Flutter (official app) - https://github.com/openfoodfacts/smooth-app |
| + | * Kotlin (official app) - https://github.com/openfoodfacts/openfoodfacts-androidapp - The official app has recently been Kotlinized. (Help to turn it into a reusable library would be welcome) |
| + | * Laravel package - https://github.com/openfoodfacts/openfoodfacts-laravel |
| + | * [[API/Javascript/NodeJS|NodeJS SDK]] - https://github.com/openfoodfacts/openfoodfacts-nodejs |
| * [[API/PHP|PHP SDK]] - https://github.com/openfoodfacts/openfoodfacts-php | | * [[API/PHP|PHP SDK]] - https://github.com/openfoodfacts/openfoodfacts-php |
| * [[API/Python|Python SDK]] - https://github.com/openfoodfacts/openfoodfacts-python (LIVE API) - https://github.com/openfoodfacts/OpenFoodFacts-APIRestPython (Local Dump) | | * [[API/Python|Python SDK]] - https://github.com/openfoodfacts/openfoodfacts-python (LIVE API) - https://github.com/openfoodfacts/OpenFoodFacts-APIRestPython (Local Dump) |
| * [[API/R|R SDK]] | | * [[API/R|R SDK]] |
− | * [[API/React Native|React Native SDK]] https://github.com/openfoodfacts/openfoodfacts-react-native | + | * React Native SDK https://github.com/openfoodfacts/openfoodfacts-react-native (Help to turn it into a reusable library would be welcome) |
| * [[API/Ruby|Ruby SDK]] - https://github.com/openfoodfacts/openfoodfacts-ruby OR gem install openfoodfacts - https://github.com/openfoodfacts/openbeautyfacts-ruby OR gem install openbeautyfacts | | * [[API/Ruby|Ruby SDK]] - https://github.com/openfoodfacts/openfoodfacts-ruby OR gem install openfoodfacts - https://github.com/openfoodfacts/openbeautyfacts-ruby OR gem install openbeautyfacts |
| * [[API/Scala|Scala SDK]] | | * [[API/Scala|Scala SDK]] |
− | * [[API/Swift|Swift SDK]] | + | * [[API/Swift|Swift SDK]] - The official app is coded in Swift. https://github.com/openfoodfacts/openfoodfacts-ios Extraction into a Swift library would be welcome. |
| Please help us bring Open Food Facts to your favorite language by contributing to SDK! | | Please help us bring Open Food Facts to your favorite language by contributing to SDK! |
| | | |
Line 82: |
Line 109: |
| * Mention Open Food Facts as the source of the data; | | * Mention Open Food Facts as the source of the data; |
| * Do not mix with other product databases (since you are then required to release them under OdBL, at your own legal risk if you didn't actually own them); | | * Do not mix with other product databases (since you are then required to release them under OdBL, at your own legal risk if you didn't actually own them); |
− | * Share any additions under the OdBL, back to the community. | + | * Share any additions under the OdBL, back to the community, using the easy API/SDK. |
| + | |
| Please join us on the Slack channel to discuss the legal and technical side of things :-) (https://slack.openfoodfacts.org) | | Please join us on the Slack channel to discuss the legal and technical side of things :-) (https://slack.openfoodfacts.org) |
| | | |
| == Roadmap == | | == Roadmap == |
− | [[API/Roadmap]] | + | |
| + | * Publishing the API on a faster server |
| + | * Having a CI pipeline from the source repository to the published documentation |
| + | * Deprecating documentation on the wiki for good. |
| + | * Setting up a process to keep the API updated. |
| + | |
| + | For the API revamp, see [[API/Roadmap]]. Please note that the above goals are our priority right now (making the current API work better for everyone). |
| | | |
| == Bugs == | | == Bugs == |
Line 93: |
Line 127: |
| | | |
| You can fill in the issue report [https://github.com/openfoodfacts/openfoodfacts-server/issues/new here on GitHub] | | You can fill in the issue report [https://github.com/openfoodfacts/openfoodfacts-server/issues/new here on GitHub] |
| + | (For documentation issues, see below) |
| + | === Keeping the documentation up to date with the live API === |
| + | * Project that tracks what we have to document: https://github.com/openfoodfacts/api-documentation/issues |
| | | |
| === Known bugs === | | === Known bugs === |
Line 98: |
Line 135: |
| * API bugs: https://github.com/openfoodfacts/openfoodfacts-server/labels/api | | * API bugs: https://github.com/openfoodfacts/openfoodfacts-server/labels/api |
| * API milestone: https://github.com/openfoodfacts/openfoodfacts-server/milestone/8 | | * API milestone: https://github.com/openfoodfacts/openfoodfacts-server/milestone/8 |
| + | |
| + | === Yet-Undocumented APIs === |
| + | * https://github.com/openfoodfacts/api-documentation |
| | | |
| == Sister projects == | | == Sister projects == |