Changes

Jump to navigation Jump to search
link to new documentation
Line 1: Line 1:  +
<big>'''IMPORTANT:''' for more up to date information see https://openfoodfacts.github.io/openfoodfacts-server/api/</big>
 +
 
= Introduction =
 
= Introduction =
   Line 30: Line 32:  
= Generic requirements =
 
= Generic requirements =
 
These requirements are valid for all OFF-API's, whether read or write.
 
These requirements are valid for all OFF-API's, whether read or write.
 +
 +
== Field names ==
 +
For the naming of the fields of the results json the following principles are used:
 +
* Typing - the to expected type of the values is encoded in the field names, by a string at the end:
 +
** _tags - expect a String array;
 +
** _n - expect an Integer;
 +
** _t - expect a time in seconds since 1970, encoded as Integer;
 +
** _f - expect a float;
 +
** none - the default will be a String
    
== Multilingual support ==
 
== Multilingual support ==
Line 51: Line 62:  
A related question is how languages should be encoded in a resulting json. For each language dependent field the corresponding language must be known. There are three options:
 
A related question is how languages should be encoded in a resulting json. For each language dependent field the corresponding language must be known. There are three options:
 
# Adapt field names - add a postfix to a field name to indicate the language, i.e. name_fr. Draw back of this approach is that the relevant postfixes are not known before hand. A list of possible languages in the json circumvents this. However this requires more extensive programming for the api user. (This approach is currently used).
 
# Adapt field names - add a postfix to a field name to indicate the language, i.e. name_fr. Draw back of this approach is that the relevant postfixes are not known before hand. A list of possible languages in the json circumvents this. However this requires more extensive programming for the api user. (This approach is currently used).
# Simple dictionary - encode a language dependent fields as a dictionary, i.e { "en":"in english", "fr":"en français"}. This keeps the drawback that the fieldnames are not known before hand;
+
# Simple dictionary - encode a language dependent fields as a dictionary, i.e { "en":"in english", "fr":"en français"}. This keeps the drawback that the field names are not known before hand;
 
# Structured dictionary - any field that can be in a specific language can be encoded as a standard "language" dictionary: { {"languageCode":"en", "languageValue":"in english"}, {"languageCode":"fr", "languageValue":"en français"}
 
# Structured dictionary - any field that can be in a specific language can be encoded as a standard "language" dictionary: { {"languageCode":"en", "languageValue":"in english"}, {"languageCode":"fr", "languageValue":"en français"}
 
This is also valid for fields that will be in the interface language, as a translation is not always available.
 
This is also valid for fields that will be in the interface language, as a translation is not always available.
 +
 +
== Nutritional values ==
 +
=== Units ===
 +
The units that are used for each nutritional value, often leads to confusion. By defining each nutritional item as a (value,unit) tuple, this could be circumvented.
    
= Product read API =
 
= Product read API =
Line 61: Line 76:  
== result json ==
 
== result json ==
   −
=== field names ===
  −
For the naming of the fields of the results json the following principles are used:
  −
* Typing - the to expected type of the values is encoded in the field names, by a string at the end:
  −
** _tags - expect a String array;
  −
** _n - expect an Integer;
  −
** _t - expect a time in seconds since ?, encoded as Integer;
  −
** _f - expect a float;
  −
** none - the default will b a String
      
=== platform specific naming issues ===
 
=== platform specific naming issues ===
Line 75: Line 82:  
=== comments ===
 
=== comments ===
 
* The json seems to have two user groups: OFF itself and end users (apps). Can the json be split in two section that correspond to these groups as well? Not sure whether this is a good approach.
 
* The json seems to have two user groups: OFF itself and end users (apps). Can the json be split in two section that correspond to these groups as well? Not sure whether this is a good approach.
* The json can be more structured, so that it is more readible for a viewer, but also from an parsing interpreting point of view. I.e. everything that corresponds to packaging goes together.
+
* The json can be more structured, so that it is more readable for a viewer, but also from an parsing interpreting point of view. I.e. everything that corresponds to packaging goes together.
 
* Improved field-names, which clearly reflect the origin or processing of the data. This should reduce the number of questions around field s and their interpretation.
 
* Improved field-names, which clearly reflect the origin or processing of the data. This should reduce the number of questions around field s and their interpretation.
 
* version 1 of the api used a language code suffix (i.e. ''_en''), to indicate the language used for the strings. Which language codes should be looked at, depended on the content of the json itself. This implied that the field names needed to be constructed, adding extra complexity to the json decoder. Another solution is to use a dictionary to encode these strings like { "languageCode" : "en", "string": "stringValue }.
 
* version 1 of the api used a language code suffix (i.e. ''_en''), to indicate the language used for the strings. Which language codes should be looked at, depended on the content of the json itself. This implied that the field names needed to be constructed, adding extra complexity to the json decoder. Another solution is to use a dictionary to encode these strings like { "languageCode" : "en", "string": "stringValue }.
Line 94: Line 101:     
= Robotoff write API =
 
= Robotoff write API =
This api allows to write reponses to insight questions provided by the Robotoff read API.
+
This api allows to write responses to insight questions provided by the Robotoff read API.
    
= Search API =
 
= Search API =
    
* See [[Open Food Facts Search API Version 2]]
 
* See [[Open Food Facts Search API Version 2]]
 +
 +
[[Category:API]]
199

edits

Navigation menu