API di ricerca multipla di alimenti

La richiesta, passo per passo

POST /v1/foods/bulk con Content-Type: application/json, la tua intestazione X-API-Key e un corpo della forma {"ids": [...]} o {"barcodes": [...]}: esattamente uno dei due, da 1 a 100 voci. Gli ids sono stringhe UUID (quelli degli esempi di codice qui sopra sono schede reali con cui fare prove); i codici a barre vengono risolti esattamente come con GET /v1/foods/barcode/{code}, quindi un EAN-13 trova anche un prodotto salvato nella sua forma UPC-12 o GTIN-14, e il campo barcode della scheda mostra la forma salvata accanto a requested_barcode.

La validazione avviene prima di toccare il database ed è tutto o niente. Un codice a barre dentro ids, entrambi i campi o nessuno, un array vuoto o 101 voci rifiutano l'intero lotto con 422 {"error": "Validation Error", "details": [{"field": "ids.3", "message": ...}]}. Un ?lang= facoltativo (en, fr, es, de, it, bg) localizza le etichette di categoria e allergeni come nelle ricerche di una singola scheda; nomi e ingredienti in altre lingue si trovano negli array name e ingredients.

Leggere la risposta

data è un array di oggetti FoodItem costruiti dallo stesso formattatore della Food Database API, quindi un parser scritto per il singolo record funziona senza modifiche, da id, barcode e source fino a categories_tags, image_url e allergens. I dati mancanti nella fonte sono null, mai una chiave assente.

nutrition_summary contiene energy_kcal, proteins_g, carbs_g, fat_g, sugars_g e fiber_g per 100 g. È null per intero solo quando il prodotto non ha alcuna riga di nutrienti; una riga a cui manca un valore mostra null solo per quella chiave. Testi d'etichetta come quantity e serving_size_raw arrivano esattamente come li hanno digitati i contributori, quindi analizzali in modo difensivo.

Voci mancanti, duplicati e deriva

La risposta può essere più corta della richiesta: non c'è un 404 per voce, ma ogni id o codice a barre senza prodotto è elencato in not_found, nell'ordine della richiesta, quindi non devi mai confrontarli tu. Un id o un codice a barre inviato due volte torna come una sola scheda: elimina i duplicati prima dell'invio, così ognuno dei 100 posti conta.

Gli id sono deterministici, derivati dalla fonte e dal suo identificativo di prodotto, quindi un prodotto mantiene il suo id tra le reimportazioni. Se un id salvato smette di risolversi, il prodotto non è più nel catalogo con quell'identità: segna la riga come obsoleta e risolvila di nuovo con la Barcode Lookup API o la Food Search API invece di eliminarla.

Quota e calcolo dei limiti

Una chiamata bulk è una richiesta contro la quota giornaliera e un token dal bucket al secondo, qualunque sia il numero di id. L'ordine del middleware è autenticazione, limite al secondo, controllo del piano, poi quota giornaliera, quindi un 401, un 429 per limite di frequenza o il 403 per Starter non consumano mai una richiesta giornaliera. Un 422 sì, perché la convalida avviene dopo il conteggio della quota; controlla gli UUID lato client.

Leggi gli header a ogni 200: X-RateLimit-Second-Limit, X-RateLimit-Burst-Capacity e X-RateLimit-Second-Remaining per il bucket per chiave, X-RateLimit-Account-Limit e X-RateLimit-Account-Remaining per l'aggregato al secondo su tutte le chiavi dell'account, e X-RateLimit-Daily-Limit, X-RateLimit-Daily-Remaining e X-RateLimit-Daily-Reset (sugli account normali) per il budget giornaliero condiviso e il suo reset a mezzanotte UTC. La POST non porta alcun header Cache-Control, quindi nulla viene messo in cache dall'edge per te: conserva ciò che recuperi.

Sincronizzare un catalogo ogni notte

Per l'assortimento di un rivenditore, invia direttamente i codici a barre, 100 per chiamata, oppure salva l'id restituito accanto al tuo SKU e sincronizza poi per id. In entrambi i casi il job notturno non cerca mai: legge i codici salvati, elimina i duplicati, li divide in gruppi da 100, invia ogni gruppo qui e salva un checkpoint dopo ogni gruppo completato, così un catalogo più grande del budget di una notte riprende da dove si era fermato. Confronta updated_at con la tua copia per sapere cosa è cambiato.

Regola il ritmo in base agli header invece che con una pausa fissa, e tieni d'occhio X-RateLimit-Daily-Remaining affinché la sincronizzazione non affami il traffico diurno sullo stesso account. Quando una vista richiede la tabella di oltre 40 nutrienti, chiama la Nutrition API per quell'id su richiesta; accetta un id per richiesta e conta anch'essa come richiesta.

• Deduplica gli id, dividi a blocchi di 100, registra un checkpoint per blocco.
• Segna come obsoleto tutto ciò che è in not_found; ricontrollalo più tardi.
• Recupera /nutrients in modo pigro, per prodotto, non nella sincronizzazione.