API за групово търсене на храни

Заявката, стъпка по стъпка

POST /v1/foods/bulk с Content-Type: application/json, хедъра ти X-API-Key и тяло във вида {"ids": [...]} или {"barcodes": [...]} — точно едно от двете, от 1 до 100 елемента. ids са UUID низове (тези в примерите с код по-горе са реални записи за тестове); баркодовете се намират точно както с GET /v1/foods/barcode/{code}, така че EAN-13 намира и продукт, записан във формата UPC-12 или GTIN-14, а полето barcode на записа показва записаната форма до requested_barcode.

Валидацията се прави преди да се стигне до базата и е всичко или нищо. Баркод в ids, двете полета или нито едно, празен масив или 101 елемента отхвърлят цялата заявка с 422 {"error": "Validation Error", "details": [{"field": "ids.3", "message": ...}]}. Незадължителният ?lang= (en, fr, es, de, it, bg) превежда етикетите на категориите и алергените, както при търсенето на един запис; имената и съставките на други езици са в масивите name и ingredients.

Четене на отговора

data е масив от обекти FoodItem, изградени от същия форматер като API за база данни с храни, така че парсер, написан за единичния запис, работи без промяна — от id, barcode и source до categories_tags, image_url и allergens. Липсващите данни от източника са null, никога липсващ ключ.

nutrition_summary съдържа energy_kcal, proteins_g, carbs_g, fat_g, sugars_g и fiber_g на 100 g. Той е null като цяло само когато продуктът изобщо няма ред с хранителни вещества; ред, на който липсва една стойност, показва null само за този ключ. Текст от етикета като quantity и serving_size_raw пристига точно както е въведен от контрибуторите, затова парсвай защитно.

Липсващи елементи, дубликати и промени

Отговорът може да е по-кратък от заявката: няма 404 за отделен елемент, но всяко id или баркод без продукт е в not_found, в реда на заявката, така че никога не сравняваш сам. Повторено id или баркод се връща като един запис — премахни дубликатите преди изпращане, за да работи всяко от 100-те места.

Id-тата са детерминирани, получени от източника и неговия собствен идентификатор на продукта, така че продуктът запазва id си при повторен внос. Ако запазено id спре да се разрешава, продуктът вече не е в каталога под тази идентичност: маркирай реда като остарял и го разреши отново през API за търсене по баркод или API за търсене на храни, вместо да го триеш.

Квота и лимити — сметките

Едно групово извикване е една заявка от дневната квота и един токен от кофата за секунда, независимо от броя на id-тата. Редът на middleware е удостоверяване, лимит за секунда, проверка на плана, после дневна квота, така че 401, 429 от лимита или 403 за Starter никога не изразходват дневна заявка. 422 изразходва, защото валидацията се изпълнява, след като квотата е отчетена; проверявай UUID-тата от страна на клиента.

Чети заглавките при всеки 200: X-RateLimit-Second-Limit, X-RateLimit-Burst-Capacity и X-RateLimit-Second-Remaining за кофата на ключа, X-RateLimit-Account-Limit и X-RateLimit-Account-Remaining за агрегата за секунда на всички ключове на акаунта, и X-RateLimit-Daily-Limit, X-RateLimit-Daily-Remaining и X-RateLimit-Daily-Reset (при нормални акаунти) за споделения дневен бюджет и неговото нулиране в полунощ UTC. POST не носи заглавка Cache-Control, така че нищо не се кешира на ръба вместо теб: запазвай каквото си изтеглил.

Нощно синхронизиране на каталог

За асортимента на търговец изпращай директно баркодовете, по 100 на заявка, или запиши върнатото id до своя SKU и после синхронизирай по id. И в двата случая нощната задача никога не търси: чете записаните кодове, премахва дубликатите, разделя ги на групи по 100, изпраща всяка група тук и записва контролна точка след всяка завършена група, така че каталог, по-голям от бюджета за една нощ, продължава оттам, докъдето е стигнал. Сравнявай updated_at със своето копие, за да видиш какво се е променило.

Темпото задавай по заглавките, а не с фиксирано заспиване, и следи X-RateLimit-Daily-Remaining, за да не оставиш синхронизирането да лиши от квота дневния трафик на същия акаунт. Когато изглед има нужда от панела с над 40 хранителни вещества, извикай API за хранителни стойности за това id при поискване; то приема по едно id на заявка и също се брои като заявка.

• Дедупликирай id-тата, дели на групи по 100, отбелязвай напредъка за всяка група.
• Маркирай всичко в not_found като остаряло; провери го пак по-късно.
• Дръпвай /nutrients лениво, за всеки продукт отделно, не в синхронизирането.