Requêtes

Règles valables pour chaque requête : paramètres de requête, langues, ID, format, connexion et limites de taille.

Paramètres de requête

Ces paramètres peuvent être ajoutés à la plupart des endpoints pour contrôler la réponse.

full-resource

Valeur	Par défaut	Description
true	Non	Renvoie la réponse JSON complète avec tous les champs
false	Oui	Renvoie une réponse minimale (économise de la bande passante)

Quand l'utiliser : définissez full-resource=true lorsque vous avez besoin de toutes les valeurs calculées. Utilisez false (par défaut) pour des réponses plus rapides lorsque seuls les indicateurs de base (rating, co2-value) vous intéressent.

Champs inclus uniquement avec full-resource=true :

• Ventilation détaillée par ingrédient
• Toutes les valeurs nutritionnelles
• Pourcentages d'amélioration
• Valeurs de réduction

indicators

Valeur	Par défaut	Description
true	Non	Inclut le VitaScore et les indicateurs environnementaux
false	Oui	Exclut les indicateurs supplémentaires

Quand l'utiliser : définissez indicators=true lorsque vous avez besoin de la notation nutritionnelle (VitaScore) ou d'indicateurs environnementaux (empreinte hydrique, forêt tropicale, bien-être animal, saisonnalité, approvisionnement local).

Champs supplémentaires avec indicators=true :

• vita-score-points, vita-score-rating, vita-score-award
• water-footprint-rating, scarce-water-liters
• rainforest-label, rainforest-rating
• animal-treatment-label, animal-treatment-rating
• season-label, season-rating
• local-label, local-rating

nutrient-values

Valeur	Par défaut	Description
true	Non	Inclut nutrient-values-estimated-per-specified-amount pour chaque ingrédient
false	Oui	Exclut les estimations de valeurs nutritionnelles

ingredients-declaration

Valeur	Par défaut	Description
true	Non	Inclut les données analysées de ingredients-declaration pour chaque ingrédient
false	Oui	Exclut les données de déclaration des ingrédients

return-uids

Valeur	Par défaut	Description
true	Non	Inclut les champs internes uid dans la réponse pour les recettes et les ingrédients
false	Oui	Exclut les UID internes

transient (paramètre de requête)

Valeur	Par défaut	Description
true	Non	Chaque recette de la requête est transitoire : calculée et renvoyée, mais ni conservée ni comptée dans les rapports
false	Oui	Les recettes sont conservées et comptées, sauf si un élément du lot définit "transient": true

Le champ du corps d'un élément de lot a la même signification pour cette seule recette. Voir Recettes transitoires.

Localisation

L'API est conçue pour qu'une requête puisse contenir des informations sur un objet (p. ex. une recette ou une fourniture) en plusieurs langues. Chaque champ JSON soumis à la localisation a pour valeur un tableau de langues :

{
  "language": "de",
  "value": "Kürbisrisotto"
}

Le champ de langue doit contenir l'un des codes alpha-2 ISO 639-1.

Génération des ID

Les ID des recettes, des cuisines et des fournitures peuvent être générés de deux façons :

1. Requête POST : l'ID est généré par Eaternity
2. Requête PUT : vous fournissez votre propre ID dans l'URL (recommandé)

L'ID peut être toute valeur alphanumérique correspondant à cette expression régulière : [-a-zA-Z0-9+&@#/%?=~_|!:,.;]*[-a-zA-Z0-9+&@#/%=~_|]

Format

• L'API accepte du JSON dans les requêtes et renvoie du JSON dans toutes les réponses
• Seul l'encodage de caractères UTF-8 est pris en charge
• Toutes les requêtes doivent être chiffrées via SSL

SSL et Server Name Indication (SNI)

Comme Eaternity utilise des serveurs distribués, l'adresse IP du service change et est partagée entre différentes applications. Pour que SSL fonctionne, le nom d'hôte voulu (co2.eaternity.ch) doit être indiqué dans chaque requête, selon la spécification SNI :

openssl s_client -connect co2.eaternity.ch:443 -servername co2.eaternity.ch

Nous recommandons d'ajouter le certificat racine Cloudflare cloudflare_origin_rsa.pem à votre liste d'autorisation.

Limites de taille des requêtes

Les endpoints des recettes et des fournitures sont soumis à deux types de limites de taille :

• Limites souples : les requêtes ne devraient pas dépasser ces limites ; des requêtes plus grandes peuvent échouer ou être rejetées. La requête est tout de même traitée, mais sans garantie.
• Limites strictes : la requête (ou, sur les routes de lot, l'élément concerné) est rejetée avec 413 Payload Too Large.

Recettes

Description	S'applique à	Limite souple
Ingrédients par recette (comptage direct)	Routes à recette unique, et chaque élément d'un lot de recettes	100
Ingrédients par recette, sous-recettes comprises (comptage récursif)	Lot de recettes uniquement	150
Recettes par requête de lot	Lot de recettes	100

Fournitures

Description	S'applique à	Limite souple
Ingrédients par fourniture (comptage direct)	Routes à fourniture unique qui attendent un résultat	100
Fournitures par requête de lot	Lot de fournitures	5000
Ingrédients de toutes les fournitures d'une requête de lot (comptage direct)	Lot de fournitures	10000