API RESTful e i18n: come progettare la risposta?

12

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

L'API gestisce i18n attraverso un'intestazione Accept-Language nelle richieste. Ciò funziona per tutto ciò che il client deve fare tranne una funzione, in cui il client deve memorizzare le risposte di una richiesta a un singolo endpoint in tutte le impostazioni locali disponibili.

Possiamo in qualche modo progettare l'API in modo tale che il client possa afferrare tutte queste informazioni con una singola richiesta e senza rompere un progetto di API RESTful coerente e ben strutturato?

Opzioni che abbiamo considerato finora:

  • Consentendo l'inclusione di più locale nell'intestazione Accept-Language e aggiungendo versioni localizzate per tutte le localizzazioni richieste nella risposta, ciascuna identificata dal codice lingua 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 tale parametro è presente.
  • (Se nessuno dei precedenti funziona per noi) facendo più richieste per prendere tutte le versioni localizzate dal client.

Qual è l'alternativa migliore?

    
posta AMM 18.01.2017 - 22:24
fonte

1 risposta

17

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

TL; DR Backstory

C'è una intestazione Accept-Language . Nota, Accept non Accepted . È una parte standard della negoziazione del contenuto HTTP. Generalmente, la risposta imposta una sottochiave Content-Language .

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

Quindi esiste già un meccanismo di intestazione HTTP che è possibile utilizzare. Tuttavia, fai attenzione che stai trascinando un processo di negoziazione che presenta più spesso una serie di opzioni possibili e recupera una singola opzione. Avresti cambiato il senso di "ecco una lista di opzioni, dammi tutte quante!" Se stai bene, hai una soluzione.

Esiste tuttavia un considerevole dibattito sull'adeguatezza della segnalazione dei parametri dell'API REST nelle intestazioni HTTP. È un po 'come entrare in un ristorante e inviare l'ordine dettagliato all'ospite o al maître piuttosto che aspettare che il cameriere o la cameriera appaiano. Può funzionare e potrebbe funzionare bene, ad es. se l'ordine diretto all'host riguarda bevande o stuzzichini, cose che l'host può vedere rapidamente o comunicare rapidamente al server. Ma può anche essere vista come una violazione del protocollo, indirizzata al livello / livello sbagliato o al giocatore sbagliato.

Una seconda alternativa sarebbe un parametro di richiesta esplicita. Suggerisci ?all_languages=true . Sembra eccessivamente specifico. Qualcosa come lang=en,fr,es (consenti più lingue elencate) o lang=* o lang=all (specifica ogni lingua disponibile) sembra più generale. Questo potrebbe essere espresso nell'URL o nel corpo della richiesta.

In ogni caso, la tua 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, entrambi questi approcci dovrebbero funzionare bene per te. Entrambi possono essere considerati come un "design RESTful API coerente e ben strutturato". La determinazione su quale sia il migliore si basa principalmente sul tuo atteggiamento verso l'appropriatezza del portamento (e leggermente alterando il senso tipico) delle intestazioni di negoziazione del contenuto HTTP.

La mia preferenza è di non intestazioni di intermix e altri parametri come parti uguali di una richiesta API. Il parametro esplicito lang o language mi sembra più pulito. Ma dal momento che il verbo HTTP (ad esempio GET , PUT , POST , PATCH , ...) fa parte dell'intestazione, e anche critico per / intermixato con l'interpretazione della richiesta, ammetto la busta contro la distinzione dei contenuti è un po 'artificiale e sfocato. Come con la maggior parte delle decisioni di progettazione, i veri esperti rispondono in modo diverso, e YMMV.

    
risposta data 19.01.2017 - 00:25
fonte

Leggi altre domande sui tag