Skip to content

Commit

Permalink
feat: knowledge API to specify which panels should be returned (#10701)
Browse files Browse the repository at this point in the history 
<!-- IMPORTANT CHECKLIST
Make sure you've done all the following (You can delete the checklist
before submitting)
- [ ] PR title is prefixed by one of the following: feat, fix, docs,
style, refactor, test, build, ci, chore, revert, l10n, taxonomy
- [ ] Code is well documented
- [ ] Include unit tests for new functionality
- [ ] Code passes GitHub workflow checks in your branch
- [ ] If you have multiple commits please combine them into one commit
by squashing them.
- [ ] Read and understood the [contribution
guidelines](https://github.com/openfoodfacts/openfoodfacts-server/blob/main/CONTRIBUTING.md)
-->
### What

Added a `knowled_panels_included=x,y` and `knowled_panels_excluded=x,y`
parameter to the API, to specify which panels should be in the response.

### Related issue(s) and discussion
<!-- Please add the issue number this issue will close, that way, once
your pull request is merged, the issue will be closed as well -->
- Fixes #9369

---------

Co-authored-by: Pierre Slamich <[email protected]>
Co-authored-by: Alex Garel <[email protected]>
  • Loading branch information
@4nt0ineB @teolemon @alexgarel
3 people authored Aug 21, 2024
1 parent 8041215 commit 384961a
Show file tree
Hide file tree
Showing 18 changed files with 6,635 additions and 153 deletions.
143 changes: 80 additions & 63 deletions docs/api/ref/api-v3.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,22 +7,22 @@ info:
As a developer, the Open Food Facts API allows you to get information
and contribute to the products database. You can create great apps to
help people make better food choices and also provide data to enhance the database.
termsOfService: 'https://openweathermap.org/terms'
termsOfService: "https://world.openfoodfacts.org/terms-of-use"
contact:
name: Open Food Facts
url: 'https://slack-ssl-openfoodfacts.herokuapp.com/'
email: contact@openfoodfacts.org
url: "https://slack.openfoodfacts.org/"
email: reuse@openfoodfacts.org
license:
name: 'License (MIT, Apache 2.0, etc)'
url: 'https://opendatacommons.org/licenses/odbl/summary/index.html'
version: '3'
name: "License (MIT, Apache 2.0, etc)"
url: "https://opendatacommons.org/licenses/odbl/summary/index.html"
version: "3"
servers:
- url: 'https://world.openfoodfacts.org'
- url: "https://world.openfoodfacts.org"
description: prod
- description: dev
url: 'https://world.openfoodfacts.net'
url: "https://world.openfoodfacts.net"
paths:
'/api/v3/product/{barcode}':
"/api/v3/product/{barcode}":
get:
tags:
- Read Requests
Expand All @@ -37,14 +37,14 @@ paths:
explode: false
schema:
type: string
example: '3017620422003'
- $ref: '#/components/parameters/cc'
- $ref: '#/components/parameters/lc'
example: "3017620422003"
- $ref: "#/components/parameters/cc"
- $ref: "#/components/parameters/lc"
- schema:
type: string
in: query
name: tags_lc
description: '2 letter language code to request names of tags in a specific language. For READ requets: if passed, all taxonomized tags of the response will include a lc_name property with the translation in the requested language, if available. Otherwise, the property value will contain the name in the original language, prefixed by the 2 language code and a colon.'
description: "2 letter language code to request names of tags in a specific language. For READ requests: if passed, all taxonomized tags of the response will include a `lc_name` property with the translation in the requested language, if available. Otherwise, the property value will contain the name in the original language, prefixed by the 2 language code and a colon."
- schema:
type: string
in: query
Expand All @@ -58,8 +58,25 @@ paths:
* "all": returns all fields except generated fields that need to be explicitly requested such as "knowledge_panels".
Defaults to "all" for READ requests. The "all" value can also be combined with fields like "attribute_groups" and "knowledge_panels".'
- schema:
type: string
example: "health_card, environment_card"
required: false
in: query
name: knowledge_panels_included
description: |-
When knowledge_panels are requested, you can specify which panels should be in the response. All the others will be excluded.
- schema:
type: string
example: "health_card, environment_card"
required: false
in: query
name: knowledge_panels_excluded
description: |-
When knowledge_panels are requested, you can specify which panels to exclude from the response. All the others will be included.
If a panel is both excluded and included (with the knowledge_panels_excluded parameter), it will be excluded.
responses:
'200':
"200":
description: OK
content:
application/json:
Expand All @@ -80,10 +97,10 @@ paths:
required: true
description: 'Barcode of the product to create or update, or "test" to analyze the product data sent without creating or updating a product'
patch:
summary: 'WRITE Product - Create or update product, or analyze test product (API V3 - Implementation in progress)'
summary: "WRITE Product - Create or update product, or analyze test product (API V3 - Implementation in progress)"
operationId: patch-api-v3-product-barcode
responses:
'200':
"200":
description: |-
The response will include a "product" structure. The fields returned in this structure will depend on the value of the "fields" input field:
Expand All @@ -108,44 +125,44 @@ paths:
value:
status: success_with_errors
result:
id: 'en:product-updated'
id: "en:product-updated"
en_name: Product updated
lc_name: Produit mis à jour
errors:
- message:
id: 'en:sugars-higher-than-carbohydrates'
id: "en:sugars-higher-than-carbohydrates"
name: Sugars higher than carbohydrates
lc_name: Sucres plus élevés que les glucides
description: Sugars (40g) are higher than carbohydrates (35g).
lc_description: Les sucres (40g) sont plus élévés que les glucdes.
field:
id: nutriment.sugars
value: '40'
value: "40"
impact:
id: 'en:nutrients-not-updated'
id: "en:nutrients-not-updated"
name: Nutrients not updated
lc_name: Nutriments non mis à jour
description: The nutrients were not updated.
lc_description: Les nutriments n'ont pas été mis à jour.
product:
packagings:
- material: 'en:pp-polypropylene'
number: '2'
recycling: 'en:discard'
shape: 'en:lid'
- material: 'en:non-corrugated-cardboard'
number: '1'
recycling: 'en:recycle'
shape: 'en:box'
- material: "en:pp-polypropylene"
number: "2"
recycling: "en:discard"
shape: "en:lid"
- material: "en:non-corrugated-cardboard"
number: "1"
recycling: "en:recycle"
shape: "en:box"
weight: 120
- material: 'en:paper-and-fibreboard-aluminium'
number: '2'
recycling: 'en:recycle'
shape: 'en:seal'
- material: 'en:clear-glass'
number: '2'
recycling: 'en:recycle'
shape: 'en:jar'
- material: "en:paper-and-fibreboard-aluminium"
number: "2"
recycling: "en:recycle"
shape: "en:seal"
- material: "en:clear-glass"
number: "2"
recycling: "en:recycle"
shape: "en:jar"
quantity: 200 ML
quantity_value: 200
quantity_unit: ml
Expand Down Expand Up @@ -181,7 +198,7 @@ paths:
value:
lc: fr
cc: fr
fields: 'product_name,packagings'
fields: "product_name,packagings"
tags_lc: fr
userid: string
password: string
Expand All @@ -190,21 +207,21 @@ paths:
packagings:
- number_of_units: 6
shape:
id: 'en:bottle'
id: "en:bottle"
material:
id: 'en:plastic'
id: "en:plastic"
recycling:
id: 'en:recycle'
id: "en:recycle"
quantity_per_unit: 25 cl
weight_measured: 10
packagings_add:
- number_of_units: 6
shape:
id: 'en:bottle'
id: "en:bottle"
material:
id: 'en:plastic'
id: "en:plastic"
recycling:
id: 'en:recycle'
id: "en:recycle"
quantity_per_unit: 25 cl
weight_measured: 10
application/xml:
Expand All @@ -225,7 +242,7 @@ paths:
summary: Get taxonomy entries suggestions
tags: []
responses:
'200':
"200":
description: OK
content:
application/json:
Expand All @@ -241,10 +258,10 @@ paths:
type: string
matched_synonyms:
type: object
description: |
Dictionary of strings associating canonical names (as seen in suggestions field) with the synonym that best matches the query. An entry is present for all suggestions, even when the synonym is the same with the canonical name.
This value is present only if get_synonyms parameter is present.
description: |
Dictionary of strings associating canonical names (as seen in suggestions field) with the synonym that best matches the query. An entry is present for all suggestions, even when the synonym is the same with the canonical name.
This value is present only if get_synonyms parameter is present.
additional_properties:
type: string
operationId: get-api-v3-taxonomy_suggestions-taxonomy
Expand All @@ -265,14 +282,14 @@ paths:
If a string is passed, an additional sort is done to put first suggestions that start with the string, followed by suggestions with a word that start with the string, and then suggestions that contain the string anywhere.
parameters:
- $ref: ./api.yml#/components/parameters/tagtype
- $ref: '#/components/parameters/cc'
- $ref: '#/components/parameters/lc'
- $ref: "#/components/parameters/cc"
- $ref: "#/components/parameters/lc"
- schema:
type: string
example: pe
in: query
name: string
description: 'Optional string used to filter suggestions (useful for autocomplete). If passed, suggestions starting with the string will be returned first, followed by suggestions matching the string at the beginning of a word, and suggestions matching the string inside a word.'
description: "Optional string used to filter suggestions (useful for autocomplete). If passed, suggestions starting with the string will be returned first, followed by suggestions matching the string at the beginning of a word, and suggestions matching the string inside a word."
- schema:
type: string
example: yougurts
Expand All @@ -289,7 +306,7 @@ paths:
type: string
in: query
name: limit
description: 'Maximum number of suggestions. Default is 25, max is 400.'
description: "Maximum number of suggestions. Default is 25, max is 400."
- schema:
type: string
in: query
Expand All @@ -300,10 +317,10 @@ paths:
in: query
name: term
description: Alias for the "string" parameter provided for backward compatibility. "string" takes precedence.
'/api/v3/tag/{tagtype}/{tag_or_tagid}':
"/api/v3/tag/{tagtype}/{tag_or_tagid}":
parameters:
- $ref: '#/components/parameters/cc'
- $ref: '#/components/parameters/lc'
- $ref: "#/components/parameters/cc"
- $ref: "#/components/parameters/lc"
- schema:
type: string
example: categories
Expand All @@ -316,12 +333,12 @@ paths:
name: tag_or_tagid
in: path
required: true
description: 'Tag name (e.g. yogurts) or tag id (e.g. en:yogurts)'
description: "Tag name (e.g. yogurts) or tag id (e.g. en:yogurts)"
get:
summary: Get knowledge panels for a tag
tags: []
responses:
'200':
"200":
description: OK
content:
application/json:
Expand Down Expand Up @@ -368,7 +385,7 @@ paths:
summary: Revert a product to a previous revision
tags: []
responses:
'200':
"200":
description: OK
content:
application/json:
Expand Down Expand Up @@ -400,23 +417,23 @@ components:
cc:
schema:
type: string
example: 'us'
example: "us"
in: query
name: cc
required: false
description: '2 letter code of the country of the user. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the country may be inferred by the IP address of the request.'
description: "2 letter code of the country of the user. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the country may be inferred by the IP address of the request."
lc:
schema:
type: string
example: 'fr'
example: "fr"
in: query
name: lc
required: false
description: '2 letter code of the language of the user. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the language may be inferred by the Accept-Language header of the request.'
description: "2 letter code of the language of the user. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the language may be inferred by the Accept-Language header of the request."
code:
schema:
type: string
example: '4251105501381'
example: "4251105501381"
in: query
name: code
description: Barcode of the product
Expand Down
Loading

0 comments on commit 384961a

Please sign in to comment.