Changes

Jump to navigation Jump to search
463 bytes added ,  06:42, 3 May 2020
Line 1: Line 1:  
[[Category:Developer]] [[Category:API]]
 
[[Category:Developer]] [[Category:API]]
   −
== Introduction ==
+
= NEW version of the documentation =
 +
 
 +
The new version of the documentation is available here:
 +
'''🚀 [https://documenter.getpostman.com/view/8470508/SVtN3Wzy https://documenter.getpostman.com/view/8470508/SVtN3Wzy] 🚀'''
 +
 
 +
= Previous version of the documentation =
 +
 
 
=== 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'''.
 
# <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 :-)
    
=== Before using the API ===
 
=== Before using the API ===
* Some products are incomplete.  
+
* 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.'''
 
* '''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
+
* When doing averages, computations... filter incomplete products to avoid issues.
 
* Assume the data is not reliable until the product is marked as complete.
 
* 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.'''
+
* '''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>
 
* <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 ===
 
=== 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.
+
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.
 
It is also used by several applications and while not yet stable, doesn't change much.
Line 27: Line 34:     
== READ operations ==
 
== READ operations ==
For more details please look at [[API/Read]]
+
For more information, see [[API/Read]]
    
=== Technical details ===
 
=== Technical details ===
 
* 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 an 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: CoolFoodApp - Android - Version 1.0 - https://coolfoodapp.com</code>)
    
== WRITE operations ==
 
== WRITE operations ==
Please look at [[API/Write]]
+
For more information, see [[API/Write]]
    
=== Use cases ===
 
=== Use cases ===
* You can add photos and informations to Open Food Facts using the API.  
+
* 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.
 
** 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.
 
** Several apps already enable more advanced editing. Gamification would be welcome.
Line 44: Line 51:     
=== 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.net (ask for the password on Slack)
+
* You should do all your test edits on https://world.openfoodfacts.dev (ask for the password on Slack)
    
=== Conventions for the API ===
 
=== Conventions for the API ===
Line 66: Line 73:  
* [[API/Java|Java SDK]]
 
* [[API/Java|Java SDK]]
 
* [[API/Javascript|JavaScript SDK]]
 
* [[API/Javascript|JavaScript SDK]]
 +
* [[API/Laravel|Laravel package]] - https://github.com/openfoodfacts/openfoodfacts-laravel
 
* [[API/Javascript/NodeJS|NodeJS SDK]]
 
* [[API/Javascript/NodeJS|NodeJS SDK]]
 
* [[API/Perl|Perl SDK]]
 
* [[API/Perl|Perl SDK]]
Line 85: Line 93:     
== Roadmap ==
 
== Roadmap ==
[[API/Roadmap]]
+
See [[API/Roadmap]]
    
== Bugs ==
 
== Bugs ==
Line 91: Line 99:  
Do not hesitate to file a bug if you find an issue in the API, or need an improvement!
 
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]  
+
You can fill in the issue report [https://github.com/openfoodfacts/openfoodfacts-server/issues/new here on GitHub]
 +
 
 
=== Known bugs ===
 
=== Known bugs ===
 
* General bugs: https://github.com/openfoodfacts/openfoodfacts-server/issues
 
* General bugs: https://github.com/openfoodfacts/openfoodfacts-server/issues
2

edits

Navigation menu