API за база данни с храни

Какво прави една заявка

GET /v1/foods/{id} приема UUID, който си получил от търсене или от търсене по баркод, и връща целия нормализиран запис. Няма избор на полета и няма странициране: записът за 62ea12b8-b260-c288-5c38-3a4906f5d6dd (баркод 5449000000996, source openfoodfacts) се връща с всеки ключ от схемата на 200, а всичко, което липсва в източника, е null, а не пропуснато.

Удостовери се със заглавката X-API-Key. Единственият незадължителен вход е ?lang=, един от en, fr, es, de, it или bg. Той добавя category_localized, category_segments_localized и allergens_localized и оставя всички други ключове непроменени, така че добавянето на lang по-късно никога не чупи съществуващ парсер. Всеки отговор носи и заглавка X-Request-Id, която да цитираш в заявки към поддръжката.

Имена, съставки и основното вписване

name и ingredients са масиви от {lang, text}. Първото вписване има lang main и повтаря name_default и ingredients_default; product_lang ти казва кой реален език е това. В записа на Coca-Cola основното име е Original Taste, вписването fr гласи Coca-Cola en canette, а вписването bg — Кока-Кола. Избери вписването, съвпадащо с езика на интерфейса ти, и се връщай към name_default.

Очаквай ingredients да е по-дълъг от броя на езиците: Open Food Facts съхранява текста на съставките по вариант на опаковката, така че един и същ lang може да се появи повече от веднъж в записа, често с еднакъв текст, както тук. Дедупликирай по lang и запази първото срещане. Текстът е въведен от контрибутори и се връща както е; вписването ar тук съдържа фрагменти от етикет, които не са съставки, затова валидирай, преди да го парсваш в структури.

Категория, тагове, алергени и lang

category е един низ със запетаи от общо към конкретно: Beverages and beverages preparations,Beverages,Carbonated drinks,Sodas,Colas,pt:bebidas cafeína. Раздели по запетая; последното ниво е най-конкретното. categories_tags съдържа същите нива като машинни тагове (en:beverages, en:carbonated-drinks, en:colas) и е стабилната стойност за филтриране или групиране, защото низът за показване се променя, когато контрибутори редактират продукта.

allergens и traces използват същите тагове от вида en:milk, както и countries (en:albania, en:austria, en:belgium) и labels. null означава, че източникът не е заявил нищо, а не че продуктът е без алергени; този запис има allergens: null и traces: null, така че предупреждение за алергии трябва да гласи „неизвестно“, а не „няма“.

С ?lang=bg API добавя category_localized като един преведен низ, category_segments_localized с по едно вписване за всяко ниво на йерархията и allergens_localized, успореден на allergens. Ниво или таг без запис в речника е null вътре в масива, затова пази индекса подравнен с categories_tags или allergens и за null позициите се връщай към английския таг.

Оценки, размер на порцията и обобщени хранителни вещества

nutriscore е малка буква (тук e), nova_group е число (4), а ecoscore_grade е низ, който може да е буква или стойност-заместител като not-applicable, което връща тази напитка. Третирай и трите като nullable и не съпоставяй not-applicable с цветна лента.

serving_size_raw и quantity са свободен текст, копиран от етикета. serving_size_raw гласи 1 can (330 ml) и става за показване; quantity гласи 0kg в този запис — грешка на контрибутор, затова никога не изчислявай тегло на опаковката от него без проверка за смисленост.

nutrition_summary дава шест стойности на 100 g: energy_kcal, proteins_g, carbs_g, fat_g, sugars_g и fiber_g. Всяка може да е null самостоятелно, а обектът може да е null, когато източникът няма таблица с хранителни стойности. Покрива ред от списък или бързо сравнение; пълните над 40 хранителни вещества се намират в API за хранителни стойности на /v1/foods/{id}/nutrients със същото id.

Стабилни id-та, кеширане и обичайният поток

Id е детерминирано, получено от източника и собствения идентификатор на продукта в източника, така че един и същ продукт получава един и същ UUID при всеки повторен внос. Пази id-тата в собствените си таблици и ги извличай отново след месеци без стъпка на пренасочване. barcode е nullable в схемата, затова предпочитай id пред barcode като ключ за връзка.

Отговор 200 носи Cache-Control: public, max-age=300, а 404 — max-age=60, така че CDN или HTTP кеш пред услугата ти ги спазва без конфигурация. Ако кешираш в собствената си база данни, използвай ключ id плюс lang, защото локализираните ключове се различават по език.

Обичайният поток: вземи id от API за търсене на храни или API за търсене по баркод, запази го и викай тази крайна точка, когато изглед с детайли има нужда от пълния запис. За да обновиш много запазени id-та наведнъж, API за групово търсене на храни приема списък в една заявка от Starter нагоре. Изображенията са снимки от контрибутори на Open Food Facts, хоствани в images.openfoodfacts.org, а записи от други източници може да нямат такива, затова показвай заместваща картинка, когато image_url е null.