Una piattaforma API impone solo la ricezione di richieste JSON?

Scegli tra quali formati vuoi supportare. Rileva il tipo di contenuto utilizzando l'intestazione Content-type della richiesta; se non corrisponde a nessuno dei tuoi tipi supportati, rifiuta la richiesta con un codice di stato 415 (o uno più generico, come 404 o 500, a seconda se sei disposto a dire al cliente cosa è andato storto o meno). Se corrisponde, verifica almeno che la richiesta sia ben formata prima di eseguire qualsiasi elaborazione.

Se controlli sia il client che il server, o sei in grado di determinare il protocollo, non ha molto senso supportare più di un tipo di contenuto per i tuoi messaggi normali - basta specificare cosa ti aspetti, e rifiuta qualsiasi altra cosa.

Inoltre, si noti che è spesso più semplice utilizzare i dati POST regolari anziché JSON per la richiesta: ad es. l'API jQuery Ajax lo rende super-diretto e molti dei motivi per l'utilizzo di JSON per la risposta (stessa politica di origine, dati strutturati, analisi semplice e veloce in javascript) spesso non si applicano alla richiesta.

La tua API deve essere in grado di comprendere la richiesta.

Come puoi farlo se accetti formati casuali.

Un'API consiste nella definizione dei formati, dei valori accettabili contenuti all'interno e della sequenza in cui vengono scambiati.

Se lo desideri, puoi specificare che la tua API accetta anche richieste XML o forse richieste di url semplici.

GitHub ha specificato un'API basata su JSON e respinge giustamente qualsiasi richiesta che non sia JSON valida.

Penso che anche il fatto di consentire le normali richieste di formdata HTTP fornisca alcuni vantaggi pratici su una pura API JSON. Hai già menzionato il caricamento dei file, dove usare JSON è almeno complicato; ma anche le richieste normali sono vantaggiose in termini di semplicità.

HTTP ha già due formati per il passaggio dei parametri, perché non usarli?

Penso che questa sia una questione di approccio, e tu hai ragione nel "non vedere i benefici" di tale restrizione. Il tuo servizio ha un'API definita; alcune voci richiedono dati strutturati (comandi e oggetti dati), altri elaborano flussi (caricamento file). Se lo vedo in questo modo, non vedo alcun problema.

• Se devi accettare qualcosa come stream, non forzare nessuno a utilizzare un formato improprio (ora JSON), ma permetti loro di inviarti quel file nel modo più naturale. Non si tratta di "infrangere" alcune regole, ma il modo più semplice per fare il lavoro. BACIO.
• Se devi elaborare le gerarchie di dati dal client: comandi e oggetti, sì, è bello dare uno, e forse il modo più semplice per inviarti gerarchie, JSON va bene. Per i tuoi clienti.

Ma per te all'interno del servizio, non è vantaggioso vedere effettivamente JSON, perché si tratta solo di una sintassi del flusso e dei componenti del gestore (lo stesso esiste per XML e forse anche altri formati). I tuoi codici non hanno bisogno di JSON, hanno bisogno di gerarchie di dati. Quindi il mio consiglio qui è di nascondere il fatto che ora usi il formato e i gestori JSON, da tutti i tuoi codici di livello superiore. Le opzioni:

• deserializza in istanze di oggetti reali all'interno della tua piattaforma,
• converti in una gerarchia di Maps, dizionari o simili
• o nascondi gli oggetti del nodo JSON reali dietro una semplice interfaccia con i metodi getAttribute, getChildren, ecc.

Qualche tempo dopo potresti non essere in grado di forzare un client a usare JSON, perché i loro sistemi comunicano attraverso XML, possono solo usare forme semplici senza JavaScript, o i loro dati sono in realtà in un database. Allora amerai il concetto di avere JSON invisibile al resto del tuo codice con uno dei metodi sopra indicati: dovrai solo scrivere il prossimo wrapper per quel XML (o il pacchetto di parametri di richiesta HTTP, qualunque cosa), e hai finito: lo stesso API e codice possono essere raggiunti tramite un altro "linguaggio dei dati".

Almeno questo è come lo vedo io.