Sto costruendo la mia prima seria API. Sto cercando di decidere in che modo gli utenti devono inviare i dati POST.
Potrei permetterli alle variabili POST, che è ciò che fanno i moduli HTML.
param1=foo¶m2=bar
Oppure posso lasciarli POST JSON, il che ha anche senso perché restituirò una risposta JSON all'utente.
{"param1":"&","param2":"bar"}
Esiste uno standard formale su quale di questi dovrebbe essere usato? Ci sono forti argomenti a favore o contro uno di questi approcci?
JSON è (di gran lunga) l'opzione più flessibile e moderna dei due, quindi mi piacerebbe farlo. Soprattutto se hai già deciso di restituire una risposta in JSON.
Detto questo, non c'è motivo per cui non puoi supportare entrambi, se questo è vantaggioso per i consumatori della tua API. I moduli HTML inviano il loro contenuto a una richiesta HTTP in cui l'intestazione HTTP Content-Type verrà impostata su application/x-www-form-urlencoded , mentre il tipo di contenuto corretto per JSON è application/json .
Alcuni framework, ad es. API Web ASP.NET offrono alcuni serializzazione automatici della posta in arrivo richiesta (che si tratti di XML o JSON, non sono sicuro che questo framework supporti la codifica dei moduli), sollevando da te l'onere di questo compito.
Se stai creando API REST, puoi utilizzare la specifica Swagger ; è un formato di definizione (YAML) per descrivere API RESTful che creano un'interfaccia per lo sviluppo e il consumo di un'API facilmente mappando le risorse e le operazioni ad esso associate. È indipendente dal linguaggio, quindi puoi generare servizi per molti linguaggi lato server / client, è leggibile e soprattutto genera una buona documentazione delle specifiche API.
Dopo averli post json, sii più versatile e preciso nelle strutture di dati che ricevi; tuttavia, le variabili POST consentono alla tua API di essere facilmente utilizzata dai browser web.
Se sai che le richieste saranno sempre da server a server, o hai input molto complessi, vorrei andare con JSON. Se i tuoi input sono molto semplici, renderà la tua API più facile da usare se usi POST vars.
Or I can let them POST JSON, which also makes sense because I will be returning a JSON response to the user.
Bene, il formato della risposta non dovrebbe limitare o condizionare il formato della richiesta.
Potrebbe interessarti la legge di Postel, nota anche come principio di robustezza .
È bene supportare diversi formati di rappresentazione sia per la richiesta che per la risposta. La chiave della robustezza risiede nella rigida rappresentazione della risorsa (modello o struttura dati), non nel suo formato (json, xml, csv).
Quindi, riguardo alla domanda. Una buona pratica potrebbe supportare entrambi (stringhe di quey e corpo della richiesta).
Solo una piccola considerazione relativa alla sicurezza dell'API. Per gli endpoint destinati a comunicare dati sensibili (password, token, dati personali) si consiglia di non pubblicare i dati tramite stringhe di query. Usa invece l'approccio JSON o le intestazioni http.
La pubblicazione dell'oggetto json consente una maggiore flessibilità, specialmente se si desidera utilizzare DateTime come uno dei parametri. Anche la stringa di query è limitata in lunghezza se i parametri sono pesanti.
Tuttavia, per le semplici richieste Post puoi fornire entrambe le opzioni, è un metodo extra in Asp.Net.
Leggi altre domande sui tag architecture api design-patterns