Requests

Regeln, die für jeden Request gelten: Query-Parameter, Sprachen, IDs, Format, Verbindung und Grössenlimits.

Query-Parameter

Diese Parameter können den meisten Endpoints angefügt werden, um die Response zu steuern.

full-resource

Wert	Standard	Beschreibung
true	Nein	Gibt die vollständige JSON-Response mit allen Feldern zurück
false	Ja	Gibt eine minimale Response zurück (spart Bandbreite)

Wann verwenden: Setzen Sie full-resource=true, wenn Sie alle berechneten Werte brauchen. Verwenden Sie false (Standard) für schnellere Responses, wenn Sie nur die Kernwerte (rating, co2-value) brauchen.

Felder, die nur mit full-resource=true enthalten sind:

• Detaillierte Aufschlüsselung pro Zutat
• Alle Nährwerte
• Verbesserungsprozente
• Reduktionswerte

indicators

Wert	Standard	Beschreibung
true	Nein	Enthält den VitaScore und die Umweltindikatoren
false	Ja	Schliesst zusätzliche Indikatoren aus

Wann verwenden: Setzen Sie indicators=true, wenn Sie die Ernährungsbewertung (VitaScore) oder Umweltkennzahlen (Wasserfussabdruck, Regenwald, Tierwohl, Saisonalität, lokale Beschaffung) brauchen.

Zusätzliche Felder mit indicators=true:

• vita-score-points, vita-score-rating, vita-score-award
• water-footprint-rating, scarce-water-liters
• rainforest-label, rainforest-rating
• animal-treatment-label, animal-treatment-rating
• season-label, season-rating
• local-label, local-rating

nutrient-values

Wert	Standard	Beschreibung
true	Nein	Enthält nutrient-values-estimated-per-specified-amount für jede Zutat
false	Ja	Schliesst die geschätzten Nährwerte aus

ingredients-declaration

Wert	Standard	Beschreibung
true	Nein	Enthält die geparsten ingredients-declaration-Daten für jede Zutat
false	Ja	Schliesst die Daten der Zutatendeklaration aus

return-uids

Wert	Standard	Beschreibung
true	Nein	Enthält die internen uid-Felder für Rezepte und Zutaten in der Response
false	Ja	Schliesst die internen UIDs aus

transient (Query-Parameter)

Wert	Standard	Beschreibung
true	Nein	Jedes Rezept im Request ist transient: Es wird berechnet und zurückgegeben, aber nicht gespeichert und nicht in Berichten gezählt
false	Ja	Rezepte werden gespeichert und gezählt, ausser ein Batch-Eintrag setzt "transient": true

Das Body-Feld eines Batch-Eintrags hat dieselbe Bedeutung für dieses eine Rezept. Siehe Transiente Rezepte.

Lokalisierung

Die API ist so aufgebaut, dass ein Request Angaben zu einem Objekt (z. B. einem Rezept oder einem Einkauf) in mehreren Sprachen enthalten kann. Jedes JSON-Feld, das lokalisiert wird, hat ein Sprach-Array als Wert:

{
  "language": "de",
  "value": "Kürbisrisotto"
}

Das Feld language muss einen der alpha-2-Codes nach ISO 639-1 enthalten.

ID-Vergabe

Die IDs von Rezepten, Küchen und Einkäufen können auf zwei Arten vergeben werden:

1. POST-Request: Eaternity vergibt die ID
2. PUT-Request: Sie geben Ihre eigene ID in der URL an (empfohlen)

Die ID kann ein beliebiger alphanumerischer Wert sein, der diesem Regex-Muster folgt: [-a-zA-Z0-9+&@#/%?=~_|!:,.;]*[-a-zA-Z0-9+&@#/%=~_|]

Format

• Die API akzeptiert JSON in Requests und gibt in allen Responses JSON zurück
• Nur die Zeichenkodierung UTF-8 wird unterstützt
• Alle Requests müssen über SSL verschlüsselt sein

SSL & Server Name Indication (SNI)

Da Eaternity verteilte Server nutzt, ändert sich die IP-Adresse des Dienstes und wird von verschiedenen Anwendungen geteilt. Damit SSL funktioniert, muss der gewünschte Hostname (co2.eaternity.ch) gemäss SNI-Spezifikation bei jedem Request angegeben werden:

openssl s_client -connect co2.eaternity.ch:443 -servername co2.eaternity.ch

Wir empfehlen, das Cloudflare-Root-Zertifikat cloudflare_origin_rsa.pem auf die Whitelist zu setzen.

Grössenlimits für Requests

Für Rezept- und Einkaufs-Endpoints gelten zwei Arten von Grössenlimits:

• Weiche Limits: Requests sollten diese Limits nicht überschreiten; grössere Requests können fehlschlagen oder abgelehnt werden. Der Request wird trotzdem verarbeitet, aber ohne Garantie.
• Harte Limits: Der Request (bei Batch-Routen der einzelne Eintrag) wird mit 413 Payload Too Large abgelehnt.

Rezepte

Beschreibung	Gilt für	Weiches Limit
Zutaten pro Rezept (direkte Anzahl)	Routen für einzelne Rezepte und jeder Eintrag in einem Rezept-Batch	100
Zutaten pro Rezept inklusive Unterrezepte (rekursive Anzahl)	Nur Rezept-Batch	150
Rezepte pro Batch-Request	Rezept-Batch	100

Einkäufe

Beschreibung	Gilt für	Weiches Limit
Zutaten pro Einkauf (direkte Anzahl)	Routen für einzelne Einkäufe, die auf ein Ergebnis warten	100
Einkäufe pro Batch-Request	Einkaufs-Batch	5000
Zutaten aller Einkäufe in einem Batch-Request (direkte Anzahl)	Einkaufs-Batch	10000