API de consultation groupée d'aliments

La requête, étape par étape

POST /v1/foods/bulk avec Content-Type: application/json, votre en-tête X-API-Key et un corps de la forme {"ids": [...]} ou {"barcodes": [...]} — exactement l'un des deux, de 1 à 100 entrées. Les ids sont des chaînes UUID (celles des exemples de code ci-dessus sont de vraies fiches pour vos tests) ; les codes-barres sont résolus exactement comme par GET /v1/foods/barcode/{code} : un EAN-13 trouve un produit enregistré sous sa forme UPC-12 ou GTIN-14, et le champ barcode de la fiche indique la forme enregistrée à côté de requested_barcode.

La validation a lieu avant tout accès à la base et c'est tout ou rien. Un code-barres dans ids, les deux champs ou aucun, un tableau vide ou 101 entrées rejettent tout le lot avec 422 {"error": "Validation Error", "details": [{"field": "ids.3", "message": ...}]}. Un paramètre facultatif ?lang= (en, fr, es, de, it, bg) traduit les libellés de catégorie et d'allergènes comme pour les consultations d'une seule fiche ; les noms et ingrédients dans d'autres langues se trouvent dans les tableaux name et ingredients.

Lire la réponse

data est un tableau d'objets FoodItem construits par le même formateur que l'API de base de données alimentaire : un parseur écrit pour la fiche unique fonctionne tel quel, de id, barcode et source jusqu'à categories_tags, image_url et allergens. Les données manquantes à la source valent null, jamais une clé absente.

nutrition_summary contient energy_kcal, proteins_g, carbs_g, fat_g, sugars_g et fiber_g pour 100 g. Il ne vaut null en entier que lorsque le produit n'a aucune ligne de nutriments ; une ligne à laquelle il manque une valeur affiche null pour cette seule clé. Les textes d'étiquette comme quantity et serving_size_raw arrivent exactement tels que les contributeurs les ont saisis : analysez-les avec prudence.

Éléments manquants, doublons et dérive

La réponse peut être plus courte que la requête : il n'y a pas de 404 par élément, mais chaque id ou code-barres sans produit figure dans not_found, dans l'ordre de la requête — inutile de comparer vous-même. Un id ou un code-barres présent deux fois revient comme une seule fiche : dédoublonnez avant l'envoi pour que chacune des 100 places serve.

Les id sont déterministes, dérivés de la source et de son propre identifiant produit : un produit garde son id d'une réimportation à l'autre. Si un id stocké ne se résout plus, le produit n'est plus dans le catalogue sous cette identité : marquez la ligne comme périmée et résolvez-la à nouveau via l'API de recherche par code-barres ou l'API de recherche alimentaire plutôt que de la supprimer.

Calcul du quota et des limites de débit

Un appel groupé compte pour une requête dans le quota quotidien et un jeton du compteur par seconde, quel que soit le nombre d'id. L'ordre des middlewares est authentification, limite par seconde, contrôle du forfait, puis quota quotidien : un 401, un 429 de limite de débit ou le 403 Starter ne consomment jamais de requête quotidienne. Un 422, si, car la validation a lieu après le décompte du quota ; vérifiez les UUID côté client.

Lisez les en-têtes de chaque 200 : X-RateLimit-Second-Limit, X-RateLimit-Burst-Capacity et X-RateLimit-Second-Remaining pour le compteur par clé, X-RateLimit-Account-Limit et X-RateLimit-Account-Remaining pour l'agrégat par seconde de toutes les clés du compte, et X-RateLimit-Daily-Limit, X-RateLimit-Daily-Remaining et X-RateLimit-Daily-Reset (sur les comptes normaux) pour le budget quotidien partagé et sa réinitialisation à minuit UTC. Le POST ne porte pas d'en-tête Cache-Control, rien n'est donc mis en cache en périphérie pour vous : stockez ce que vous récupérez.

Synchroniser un catalogue chaque nuit

Pour l'assortiment d'un distributeur, envoyez directement les codes-barres, 100 par appel, ou enregistrez l'id renvoyé à côté de votre référence et synchronisez ensuite par id. Dans les deux cas, la tâche nocturne ne cherche jamais : elle lit les codes stockés, les dédoublonne, les découpe en groupes de 100, envoie chaque groupe ici et enregistre un point de reprise après chaque groupe terminé, pour qu'un catalogue plus grand que le budget d'une nuit reprenne là où il s'est arrêté. Comparez updated_at avec votre copie pour savoir ce qui a changé.

Réglez le rythme d'après les en-têtes plutôt qu'avec une pause fixe, et surveillez X-RateLimit-Daily-Remaining pour que la synchronisation n'affame pas le trafic de journée du même compte. Quand une vue a besoin du tableau de 40+ nutriments, appelez l'API de nutrition pour cet id à la demande ; elle prend un id par requête et compte aussi comme une requête.

• Dédoublonnez les id, découpez par 100, point de reprise par groupe.
• Marquez tout ce qui figure dans not_found comme périmé ; revérifiez plus tard.
• Récupérez /nutrients à la demande, produit par produit, pas dans la synchronisation.