Request

Regole valide per ogni request: query parameter, lingue, ID, formato, connessione e limiti di dimensione.

Query parameter

Questi parametri si possono aggiungere alla maggior parte degli endpoint per controllare la response.

full-resource

Valore	Default	Descrizione
true	No	Restituisce la response JSON completa con tutti i campi
false	Sì	Restituisce una response minima (risparmia banda)

Quando usarlo: impostate full-resource=true quando vi servono tutti i valori calcolati. Usate false (default) per response più rapide quando vi servono solo le metriche principali (rating, co2-value).

Campi inclusi solo con full-resource=true:

• Suddivisioni dettagliate per ingrediente
• Tutti i valori nutrizionali
• Percentuali di miglioramento
• Valori di riduzione

indicators

Valore	Default	Descrizione
true	No	Include il VitaScore e gli indicatori ambientali
false	Sì	Esclude gli indicatori aggiuntivi

Quando usarlo: impostate indicators=true quando vi serve la valutazione nutrizionale (VitaScore) o metriche ambientali (impronta idrica, foresta pluviale, benessere animale, stagionalità, provenienza locale).

Campi aggiuntivi con 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

Valore	Default	Descrizione
true	No	Include nutrient-values-estimated-per-specified-amount per ogni ingrediente
false	Sì	Esclude le stime dei valori nutrizionali

ingredients-declaration

Valore	Default	Descrizione
true	No	Include i dati di ingredients-declaration analizzati per ogni ingrediente
false	Sì	Esclude i dati della dichiarazione degli ingredienti

return-uids

Valore	Default	Descrizione
true	No	Include nella response i campi interni uid di ricette e ingredienti
false	Sì	Esclude gli UID interni

transient (query parameter)

Valore	Default	Descrizione
true	No	Ogni ricetta della request è transitoria: viene calcolata e restituita, ma non viene salvata né conteggiata nei report
false	Sì	Le ricette vengono salvate e conteggiate, a meno che un elemento del batch imposti "transient": true

Il campo del body di un elemento del batch ha lo stesso significato per quella singola ricetta. Vedere Ricette transitorie.

Localizzazione

L'API è progettata in modo che una request possa contenere informazioni su un oggetto (ad es. una ricetta o una fornitura) in più lingue. Ogni campo JSON soggetto a localizzazione ha come valore un array di lingue:

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

Il campo language deve contenere uno dei codici alpha-2 ISO 639-1.

Generazione degli ID

Gli ID di ricette, cucine e forniture possono essere generati in due modi:

1. Request POST: l'ID viene generato da Eaternity
2. Request PUT: fornite il vostro ID nell'URL (consigliato)

L'ID può essere qualsiasi valore alfanumerico conforme a questo pattern regex: [-a-zA-Z0-9+&@#/%?=~_|!:,.;]*[-a-zA-Z0-9+&@#/%=~_|]

Formato

• L'API accetta JSON nelle request e restituisce JSON in tutte le response
• È supportata solo la codifica dei caratteri UTF-8
• Tutte le request devono essere cifrate tramite SSL

SSL e Server Name Indication (SNI)

Poiché Eaternity usa server distribuiti, l'indirizzo IP del servizio cambia ed è condiviso tra diverse applicazioni. Perché SSL funzioni, l'hostname desiderato (co2.eaternity.ch) deve essere indicato in ogni request secondo la specifica SNI:

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

Raccomandiamo di inserire nella whitelist il certificato root di Cloudflare cloudflare_origin_rsa.pem.

Limiti di dimensione delle request

Gli endpoint di ricette e forniture sono soggetti a due tipi di limiti di dimensione:

• Limiti soft: le request non dovrebbero superarli; request più grandi possono fallire o essere rifiutate. La request viene comunque elaborata, ma senza garanzie.
• Limiti hard: la request (o, sulle route batch, il singolo elemento) viene rifiutata con 413 Payload Too Large.

Ricette

Descrizione	Si applica a	Limite soft
Ingredienti per ricetta (conteggio diretto)	Route per singola ricetta e ogni elemento di un batch di ricette	100
Ingredienti per ricetta, sotto-ricette incluse (conteggio ricorsivo)	Solo batch di ricette	150
Ricette per request batch	Batch di ricette	100

Forniture

Descrizione	Si applica a	Limite soft
Ingredienti per fornitura (conteggio diretto)	Route per singola fornitura che attendono un risultato	100
Forniture per request batch	Batch di forniture	5000
Ingredienti di tutte le forniture in una request batch (conteggio diretto)	Batch di forniture	10000