Migrationsleitfaden (v2 -> v2.1)

Migrationsleitfaden: v2 zu v2.1

Kurzüberblick

Gegenüber v2 führt v2.1 zwei wesentliche Änderungen ein:

1. Drei neue Standard-Attribute werden zu Food-/Search-Response-Objekten hinzugefügt:

   • standard_processing
   • standard_serving_type
   • standard_unit

2. Generic-Food-Quell-Daten wurden aktualisiert von BLS Version 3.0 auf BLS 4.0. Das kann Verfügbarkeit, Namen und IDs generischer Foods beeinflussen.

Wichtig für bestehende Integrationen:

• Die neuen Felder sind additiv, aber strikte DTO-/Deserialisierungslogik sollte aktualisiert werden.
• Bereits getrackte/ausgewertete Foods bleiben über ein internes Legacy-Mapping mindestens 6 Monate nach dem Stichtag unterstützt.

---

1) Route: GET /api/v2.1/food/{id} and GET /api/v2.1/search?query=xyz

Object: food_service.FoodDTO

Neu in v2.1 gegenüber v2

Die Responses enthalten jetzt drei zusätzliche Standard-Attribute:

• standard_processing
• standard_serving_type
• standard_unit

---

standard_processing

standard_processing beschreibt den Verarbeitungszustand, in dem ein Food am häufigsten konsumiert wird.

Beispiele:

• Nudeln können standard_processing: "boiled" haben.
• Frisches Obst kann standard_processing: "raw" haben.

Dieses Feld soll die Nährwertgenauigkeit verbessern. Beispiel: 100 g rohe Nudeln und 100 g gekochte Nudeln können sehr unterschiedliche Nährwertprofile haben, während die meisten Nutzer Nudeln üblicherweise gekocht verzehren.

Wichtiges Verhalten:

• standard_processing ist nie leer.
• Default ist "raw".
• Wenn ein standard_processing-Wert gesetzt ist, ist garantiert, dass die passende Processing-Variante für dieses Food existiert.
• Mögliche Werte und weitere Informationen finden Sie hier:

Empfohlenes Integrationsverhalten:

• Nutzen Sie standard_processing als Default-Processing-State in Ihrer UI.
• Das ist besonders wichtig für Foods, die typischerweise gekocht, zubereitet, getrocknet, abgetropft oder anderweitig verarbeitet konsumiert werden.

---

standard_serving_type

standard_serving_type gibt den Portionsgrössen-Typ an, der von Nutzern am wahrscheinlichsten ausgewählt wird.

Das kann genutzt werden, um eine Portionsgrösse vorzubelegen und Interaktion zu reduzieren.

Wichtiges Verhalten:

• standard_serving_type kann null oder leer sein.
• serving_sizes kann ebenfalls leer sein, auch wenn das selten ist.
• Ein Food kann serving_sizes haben, aber kein standard_serving_type.
• standard_serving_type kann nicht auf einen Typ verweisen, der nicht in serving_sizes existiert.
• Mögliche Serving-Keys sind hier dokumentiert:

Empfohlenes Integrationsverhalten:

• Wenn standard_serving_type vorhanden ist, wählen Sie den passenden Eintrag aus serving_sizes vor.
• Wenn standard_serving_type fehlt, nutzen Sie Ihr bestehendes Auswahlverhalten.
• Wenn keine passende Portionsgrösse existiert, erlauben Sie manuelle Eingabe von Gewicht oder Volumen.

---

standard_unit

standard_unit beschreibt die Einheit, die Nutzer typischerweise für dieses Food verwenden.

Zulässige Werte:

• "g"
• "ml"

Wichtiges Verhalten:

• standard_unit ist nie leer.
• Default ist "g".
• Dieses Feld spiegelt typische Nutzer-Eingaben wider, nicht die ernährungswissenschaftliche Klassifikation.

Das ist etwas anderes als is_solid.

Beispiel:

– Tomatensuppe kann haben:

• standard_unit: "ml" because users usually measure it as a liquid
• is_solid: true because it is treated as solid for nutritional energy-density calculations

Empfohlenes Integrationsverhalten:

• Nutzen Sie standard_unit als Default-Einheit für manuelle Mengeneingabe.
• Verwenden Sie "ml" für Produkte, die üblicherweise als Flüssigkeit gemessen werden.
• Verwenden Sie "g" für Produkte, die üblicherweise nach Gewicht gemessen werden.
• Nutzen Sie is_solid nicht, um zu entscheiden, ob Nutzer Gramm oder Milliliter eingeben sollen.

---

2) Generic food source data update: BLS 4.0

v2.1 aktualisiert die Generic-Food-Quell-Daten auf BLS Version 4.0.

Das kann zu Änderungen bei generischen Foods führen, u. a.:

• Gelöschte generische Foods
• Umbenannte generische Foods
• Neu angelegte generische Foods
• Aktualisierte Mappings zwischen alten und neuen generischen Food-Einträgen

Backward compatibility

Um bestehende Integrationen und User-Historien zu schützen, stellt Newtrition Data ein internes Legacy-Mapping bereit.

Wichtiges Verhalten:

• Nutzer können alte oder gelöschte generische Foods ggf. nicht mehr über die Suche finden.
• Bereits getrackte Foods bleiben über ein internes Mapping weiterhin auswertbar.
• Legacy-generic Foods bleiben für Auswertungen mindestens 6 Monate nach dem Cutoff unterstützt.

Beispiel:

Wenn ein Nutzer ein generisches Food vor dem BLS-4.0-Cutoff getrackt hat und dieses Food später gelöscht oder umbenannt wurde, findet der Nutzer es ggf. nicht mehr über die Suche. Auswertungen mit dem zuvor getrackten Food können jedoch weiterhin über das interne Legacy-Mapping verarbeitet werden.

Empfohlenes Integrationsverhalten:

• Gehen Sie nicht davon aus, dass alle zuvor durchsuchbaren generischen Foods weiterhin suchbar bleiben.
• Behalten Sie gespeicherte Food-Identifier für bereits getrackte Foods.
• Senden Sie gespeicherte Food-Referenzen weiterhin für Auswertungen.
• Ersetzen Sie zuvor getrackte generische Foods nicht allein aufgrund der Suchverfügbarkeit.
• Erwägen Sie, alte generische Foods in Ihrem System vor Ablauf des Kompatibilitätszeitraums zu aktualisieren oder zu remappen.

Weitere Informationen zu Legacy-Food-Daten finden Sie hier

---

Integration notes

DTO updates

Aktualisieren Sie DTOs für Food- und Search-Responses um:

{
  "standard_processing": "raw",
  "standard_serving_type": "medium_piece",
  "standard_unit": "g"
}

Beispiel mit nullable Serving-Type:

{
  "standard_processing": "raw",
  "standard_serving_type": null,
  "standard_unit": "g"
}

Recommended default selection logic

Für die Eingabe der Food-Menge ist die empfohlene Priorität:

1. standard_processing als Default-Processing-State verwenden.
2. Falls standard_serving_type vorhanden ist, den passenden serving_sizes[] Eintrag vorwählen.
3. standard_unit als Default-Einheit für manuelle Eingabe verwenden.
4. Wenn keine Portionsgrösse verfügbar ist, sollte manuelle Eingabe in standard_unit angeboten werden.

Zusammenfassung der Änderungen von v2 zu v2.1

Area	Change	Required action
Food response	Added standard_processing	Use as default processing state
Food response	Added standard_serving_type	Optionally preselect matching serving size
Food response	Added standard_unit	Use as default user-facing input unit
Search response	Added same three fields to each result	Update search DTOs and UI defaults
Generic foods	Source updated to BLS 4.0	Expect renamed, deleted, and new generic foods
Legacy foods	Internal mapping available	Existing tracked foods remain evaluable for at least 6 months