Difference between revisions of "Open Food Facts API Version 2"

From Open Food Facts wiki
Jump to navigation Jump to search
Line 22: Line 22:
 
- https://github.com/openfoodfacts/openfoodfacts-server/issues/4389
 
- https://github.com/openfoodfacts/openfoodfacts-server/issues/4389
 
- https://github.com/openfoodfacts/openfoodfacts-server/pull/4436
 
- https://github.com/openfoodfacts/openfoodfacts-server/pull/4436
= APIs =
+
= Product read API =
  
== Product read API ==
+
== call ==
  
=== call ===
+
== result json ==
  
=== result json ===
+
=== field names ===
 
 
==== field names ====
 
 
For the naming of the fields of the results json the following principles are used:
 
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:
 
* Typing - the to expected type of the values is encoded in the field names, by a string at the end:
Line 39: Line 37:
 
** none - the default will b a String
 
** none - the default will b a String
  
==== platform specific naming issues ====
+
=== platform specific naming issues ===
 
* Swift: it should be as easy as possible to decode a json with the standard Swift-libraries.
 
* Swift: it should be as easy as possible to decode a json with the standard Swift-libraries.
 
** no "-", which are not allowed in Swift variable names;
 
** no "-", which are not allowed in Swift variable names;
==== 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 readible for a viewer, but also from an parsing interpreting point of view. I.e. everything that corresponds to packaging goes together.
Line 48: Line 46:
 
* 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 }.
  
== Product write API ==
+
= Product write API =
  
== Images read API ==
+
= Images read API =
  
== Images write API ==
+
= Images write API =
  
== Robotoff read API ==
+
= Robotoff read API =
 
There is now a minimal documentation (link). The documentation needs some more explanation.
 
There is now a minimal documentation (link). The documentation needs some more explanation.
  
=== call ===
+
== call ==
  
=== result json ===
+
== result json ==
 
The result json contains fields that seem more useful to the internal workings of Robotoff than the enduser. Can these be split/structured in the json as well?
 
The result json contains fields that seem more useful to the internal workings of Robotoff than the enduser. Can these be split/structured in the json as well?
  
== 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 reponses 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]]

Revision as of 10:57, 28 October 2020

Introduction

Version 1 of the Open Food Facts API has been developed organically since 2012, often according to specific needs (in particular the OFF app), and it has been modeled on the structure of the MongoDB database (which itself has evolved organically) and on the Web site (e.g. reusing or mimicking existing CGI forms).

As a result, version 1 of the API is not as standard / simple / easy / powerful / intuitive / documented etc. as it could be.

This page is to discuss the design of a better version 2 of the API.

Desired properties wishlist

What standards should the new API follow, what overally properties should it have etc.?

You can add what you want, and we can discuss it.

Related Issues

- https://github.com/openfoodfacts/openfoodfacts-server/issues/4389 - https://github.com/openfoodfacts/openfoodfacts-server/pull/4436

Product read API

call

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

  • Swift: it should be as easy as possible to decode a json with the standard Swift-libraries.
    • no "-", which are not allowed in Swift variable names;

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 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.
  • 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 }.

Product write API

Images read API

Images write API

Robotoff read API

There is now a minimal documentation (link). The documentation needs some more explanation.

call

result json

The result json contains fields that seem more useful to the internal workings of Robotoff than the enduser. Can these be split/structured in the json as well?

Robotoff write API

This api allows to write reponses to insight questions provided by the Robotoff read API.

Search API