API RESTful e i18n: come progettare la risposta?

Stiamo progettando un'API RESTful destinata principalmente a soddisfare le esigenze di un singolo client. A causa delle sue circostanze molto particolari, questo cliente deve fare il minor numero possibile di richieste.

L'API gestisce i18n tramite un'intestazione Accept-Language nelle richieste. Questo funziona per tutte le cose che il client deve fare, tranne per una funzione, in cui il client deve archiviare le risposte di una richiesta a un singolo endpoint in tutte le impostazioni locali disponibili.

Possiamo in qualche modo progettare l'API in un modo che consenta al cliente di raccogliere tutte queste informazioni con una singola richiesta e senza interrompere una progettazione API RESTful coerente e ben strutturata?

Opzioni che abbiamo considerato finora:

• Consentire l'inclusione di più impostazioni locali nell'intestazione Accept-Language e l'aggiunta di versioni localizzate per tutte le impostazioni locali richieste nella risposta, ognuna identificata dal codice ISO 639-1 come chiave.
• Creare qualcosa come un parametro "? All_languages ​​= true" su quell'endpoint e restituire versioni localizzate per tutte le localizzazioni disponibili nella risposta se quel parametro è presente.
• (Se nessuna delle opzioni precedenti funziona per noi) fare più richieste per ottenere tutte le versioni localizzate dal client.

Qual è la migliore alternativa?

Hai descritto due modi efficaci per richiedere più lingue. O dovrebbe funzionare bene. Vorrei scegliere il parametro di richiesta della lingua esplicita per il mio codice.

TL; DR Backstory

C'è un'intestazione Accept-Language . Nota Acceptno Accepted. È una parte standard della negoziazione del contenuto HTTP. La risposta di solito ripristina un'intestazione Content-Language .

Accept-Languageè l'offerta di apertura, che offre una serie di opzioni; Content-Languageè la risoluzione, che indica quale lingua è stata scelta. La maggior parte delle Content-Languagerisposte restituisce una sola lingua, ma esiste un'opzione per fornire un elenco separato da virgole di lingue di risposta. Di solito sarebbe un contenuto misto, ma non c'è motivo per cui non possa segnalare più alternative disgiunte. Se si voleva il client per richiedere tutte le lingue disponibili, c'è già un'opzione di richiesta di jolly, *.

Quindi esiste già un meccanismo di intestazione HTTP che è possibile utilizzare. Tuttavia, tieni presente che avresti trasferito sulle spalle un processo di negoziazione che più spesso presenta una serie di possibili opzioni e recupera una singola opzione. Sposteresti il ​​senso di "ecco un elenco di opzioni, dammi tutte!" Se stai bene, hai una soluzione.

Esiste tuttavia un considerevole dibattito sull'idoneità della segnalazione dei parametri dell'API REST nelle intestazioni HTTP. È un po 'come entrare in un ristorante e cancellare il tuo ordine dettagliato per l'host o il maître piuttosto che aspettare che il cameriere o la cameriera compaiano. Può funzionare e può funzionare bene, ad esempio se l'ordine diretto all'host si riferisce a bevande o stuzzichini - cose che l'host può vedere rapidamente o comunicare rapidamente con il tuo server. Ma può anche essere visto come una violazione del protocollo, indirizzata al livello / livello sbagliato o al giocatore sbagliato.

Una seconda alternativa sarebbe un parametro di richiesta esplicita. Tu suggerisci ?all_languages=true. Sembra eccessivamente specifico. Qualcosa di simile lang=en,fr,es(consentire più lingue elencate) o lang=*o lang=all(specificare ogni lingua disponibile) sembra più generale. Questo può essere espresso nell'URL o nel corpo della richiesta.

In entrambi i casi, la risposta multilingue può essere facilmente codificata nel payload JSON restituito:

[ { "lang": "en", "content": "As Gregor Samsa awoke one morning..." },
  { "lang": "de", "content": "Als Gregor Samsa eines Morgens..." },
  ...
]

Alla fine, uno di questi approcci dovrebbe funzionare bene per te. Entrambi potrebbero essere visti come "progettazione API RESTful coerente e ben strutturata". La determinazione su quale sia meglio si basa principalmente sul tuo atteggiamento nei confronti dell'adeguatezza delle intestazioni di negoziazione dei contenuti HTTP (e leggermente alterando il senso tipico di).

La mia preferenza è quella di non mescolare intestazioni e altri parametri come parti uguali di una richiesta API. L'esplicito lango languageparametro mi sembra più pulito. Ma dal momento che il (ad esempio HTTP verb GET, PUT, POST, PATCH, ...) fa parte dell'intestazione, e anche fondamentale per / mescolati con l'interpretazione della richiesta, lo ammetto la busta contro contenuti distinzione è un po 'artificiale e confusa. Come con la maggior parte delle decisioni di progettazione, i veri esperti rispondono in modo diverso e YMMV.