|
Β |
(12 intermediate revisions by 7 users not shown) |
Line 1: |
Line 1: |
| | __NOINDEX__ |
| [[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. |
|
| |
|
| = NEW version of the documentation =
| | All information about the API can be found [https://openfoodfacts.github.io/openfoodfacts-server/api/ in the documentation]. |
| Β | |
| The new version of the documentation is available here:
| |
| * [https://world.openfoodfacts.org/files/api-documentation.html Documentation as HTML on Open Food Facts' servers]
| |
| * [https://documenter.getpostman.com/view/8470508/SVtN3Wzy Documentation on Postman] (might be slow)
| |
| Β | |
| 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 =
| |
| Β | |
| === 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'''.
| |
| # <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 :-)
| |
| Β | |
| === Before using the API ===
| |
| * Some products are incomplete.
| |
| * '''You should ensure your UX tells the final user that the product is not complete, encourage them to exercise caution and/or help complete the product.'''
| |
| * When doing averages, computations... filter incomplete products to avoid issues.
| |
| * Assume the data is not reliable until the product is marked as complete.
| |
| * '''In general, ensure the user exercises caution (for allergens...) and be upfront about possible risks.'''
| |
| * <span style="color:#d33">'''By using any part of the API you have read and understood the [[#License|license]].'''</span>
| |
| Β | |
| === Current status of the API ===
| |
| Currently, the API is used internally for the official Open Food Facts mobile applications (iOS, Android, Windows, and we need help!) and by hundreds of reuses on various topics (Nutrition, sportβ¦) and platforms (iOS, Android...), but does not yet follow good practices in API design.
| |
| Β | |
| It is also used by several applications and while not yet stable, doesn't change much.
| |
| Β | |
| You can have a look at the source code of the apps ([[Mobile_App]])
| |
| Β | |
| '''Anyone with Swagger (or equivalent knowledge) willing to help us document the API is most welcome :-)'''
| |
| Β | |
| === Getting help with the API ===
| |
| You can ask for help on using the API in the [https://openfoodfacts.slack.com/messages/api/ #api channel on Slack]. Join us to discuss your use case and get help/code from other devs.
| |
| Β | |
| == READ operations ==
| |
| For more information, see [[API/Read]]
| |
| Β | |
| === Technical details ===
| |
| * You can do READ operations using the production server.
| |
| * 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>)
| |
| Β | |
| == WRITE operations ==
| |
| For more information, see [[API/Write]]
| |
| Β | |
| === Use cases ===
| |
| * You can add photos and information to Open Food Facts using the API.
| |
| ** Letting your users add new products by uploading photos is the most common use case.
| |
| ** Several apps already enable more advanced editing. Gamification would be welcome.
| |
| * The official mobile apps can use some help.
| |
| Β | |
| === A few things ===
| |
| * '''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.
| |
| * 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)
| |
| Β | |
| === Conventions for the API ===
| |
| * fields that end with _t are dates in the UNIX timestamp format (number of seconds since Jan 1st 1970)
| |
| * fields that end with _datetime are dates in the iso8601 format: yyyy-mm-ddThh:mn:ssZ
| |
| * fields that end with _tags are comma separated list of tags (e.g. categories_tags is the set of normalized tags computer from the categories field)
| |
| * 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
| |
| Β | |
| === Ready made code you can use in your app ===
| |
| React Native: https://github.com/openfoodfacts/openfoodfacts-react-native
| |
| Β | |
| == SDKs ==
| |
| 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.
| |
| Β | |
| 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/Java|Java SDK]] - The official app used to be coded in Java. Extraction into a Java library would be welcome.
| |
| * [[API/Javascript|JavaScript SDK]] - We don't have a vanilla Javascript SDK right now
| |
| * Dart - https://github.com/openfoodfacts/openfoodfacts-dart
| |
| * 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]]
| |
| * [[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/R|R SDK]]
| |
| * 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/Scala|Scala 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!
| |
| Β | |
| == Licence ==
| |
| Open Food Facts is under the [https://opendatacommons.org/licenses/odbl/ OdBL licence] (database) and [https://creativecommons.org/licenses/by-sa/3.0 CC-BY-SA] (pictures). That has a couple of legal implications, in short:
| |
| * 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);
| |
| * 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)
| |
| Β | |
| == 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 ==
| |
| === Reporting bugs ===
| |
| Do not hesitate to file a bug if you find an issue in the API, or need an improvement!
| |
| Β | |
| You can fill in the issue report [https://github.com/openfoodfacts/openfoodfacts-server/issues/new here on GitHub]
| |
| Β | |
| === Known bugs ===
| |
| * General bugs: https://github.com/openfoodfacts/openfoodfacts-server/issues
| |
| * API bugs: https://github.com/openfoodfacts/openfoodfacts-server/labels/api
| |
| * API milestone: https://github.com/openfoodfacts/openfoodfacts-server/milestone/8
| |
| Β | |
| == Sister projects ==
| |
| === Open Pet Food Facts ===
| |
| Open Pet Food Facts behaves just like Open Food Facts. Behaviours may change over time, as we tweak it.
| |
| * https://world.openpetfoodfacts.org/api/v0/product/20106836.json
| |
| Β | |
| === Open Beauty Facts ===
| |
| [[API/OpenBeautyFacts]]
| |
| Β | |
| === Open Products Facts ===
| |
| Open Products Facts behaves mostly like Open Food Facts. Behaviours may change over time, as we tweak it.
| |