Esistono standard o best practice per strutturare le risposte JSON da un'API? Ovviamente, i dati di ogni applicazione sono diversi, quindi non mi preoccupo molto, ma piuttosto la "risposta", se vuoi. Un esempio di cosa intendo:

Richiesta riuscita:

{
  "success": true,
  "payload": {
    /* Application-specific data would go here. */
  }
}

Richiesta non riuscita:

{
  "success": false,
  "payload": {
    /* Application-specific data would go here. */
  },
  "error": {
    "code": 123,
    "message": "An error occurred!"
  }
}

Sì, sono emersi un paio di standard (anche se alcune libertà sulla definizione di standard) che sono emersi:

1. API JSON - L' API JSON copre anche la creazione e l'aggiornamento delle risorse, non solo le risposte.
2. JSend - Semplice e probabilmente quello che stai già facendo.
3. Protocollo JSON OData - Molto complicato.
4. HAL - Come OData, ma mirando ad essere HATEOAS .

Esistono anche formati di descrizione dell'API JSON:

• pavoneggiarsi
  • Schema JSON (usato da Swagger ma potresti usarlo da solo)
• WADL in JSON
• Raml
• HAL perché HATEOAS in teoria si descrive da sé.

Guida di Google JSON

Risposta risposta riuscita data

{
  "data": {
    "id": 1001,
    "name": "Wing"
  }
}

Ritorno risposta errore error

{
  "error": {
    "code": 404,
    "message": "ID not found"
  }
}

e se il tuo client è JS, puoi usare if ("error" in response) {}per verificare se c'è un errore.

Immagino che uno standard defacto non sia davvero emerso (e potrebbe non mai). Ma a prescindere, ecco la mia opinione:

Richiesta riuscita:

{
  "status": "success",
  "data": {
    /* Application-specific data would go here. */
  },
  "message": null /* Or optional success message */
}

Richiesta non riuscita:

{
  "status": "error",
  "data": null, /* or optional error payload */
  "message": "Error xyz has occurred"
}

Vantaggio: stessi elementi di massimo livello sia in casi di successo che di errore

Svantaggio: nessun codice di errore, ma se lo si desidera, è possibile modificare lo stato in un codice (positivo o negativo), oppure - È possibile aggiungere un altro elemento di livello superiore denominato "codice".

Supponendo che la tua domanda riguardi la progettazione di servizi web REST e più precisamente riguardo al successo / errore.

Penso che ci siano 3 diversi tipi di design.

1. Usa solo il codice di stato HTTP per indicare se si è verificato un errore e prova a limitarti a quelli standard (di solito dovrebbe bastare).

   • Pro: è uno standard indipendente dal tuo api.
   • Contro: meno informazioni su ciò che è realmente accaduto.

2. Usa HTTP Status + json body (anche se si tratta di un errore). Definire una struttura uniforme per gli errori (es: codice, messaggio, motivo, tipo, ecc.) E usarla per gli errori, se ha esito positivo restituire semplicemente la risposta json prevista.

   • Pro: sempre standard quando si utilizzano i codici di stato HTTP esistenti e si restituisce un json che descrive l'errore (si forniscono ulteriori informazioni su ciò che è accaduto).
   • Contro: l'output json varierà a seconda che si tratti di un errore o di successo.

3. Dimentica lo stato http (es: sempre stato 200), usa sempre json e aggiungi alla radice della risposta una risposta booleana valida e un oggetto di errore (codice, messaggio, ecc.) Che verrà popolato se si tratta di un errore, altrimenti gli altri campi (successo) sono popolati.

   • Pro: il client si occupa solo del corpo della risposta che è una stringa json e ignora lo stato (?).

   • Contro: meno standard.

Sta a te scegliere :)

A seconda dell'API sceglierei 2 o 3 (preferisco 2 per json rest apis). Un'altra cosa che ho sperimentato nella progettazione di REST Api è l'importanza della documentazione per ogni risorsa (url): i parametri, il corpo, la risposta, le intestazioni ecc. + Esempi.

Ti consiglierei anche di usare jersey (implementazione jax-rs) + genson (libreria di database di java / json). Devi solo rilasciare genson + jersey nel tuo percorso di classe e json è automaticamente supportato.

MODIFICARE:

• La soluzione 2 è la più difficile da implementare, ma il vantaggio è che puoi gestire bene le eccezioni e non solo gli errori aziendali, ma lo sforzo iniziale è più importante ma vinci a lungo termine.

• La soluzione 3 è facile da implementare sia sul lato server che sul client, ma non è così bello in quanto dovrai incapsulare gli oggetti che vuoi restituire in un oggetto risposta contenente anche l'errore responseValid +.

La RFC 7807: Problema Dettagli per HTTP API è in questo momento la cosa più vicina che abbiamo a uno standard ufficiale.

Di seguito è il formato json che instagram sta usando

{
    "meta": {
         "error_type": "OAuthException",
         "code": 400,
         "error_message": "..."
    }
    "data": {
         ...
    },
    "pagination": {
         "next_url": "...",
         "next_max_id": "13872296"
    }
}

Non sarò così arrogante nel sostenere che si tratta di uno standard, quindi userò il modulo "Preferisco".

Preferisco una risposta concisa (quando richiedo un elenco di / articoli voglio un array di articoli JSON).

Nei miei progetti utilizzo HTTP per il rapporto sullo stato, un 200 restituisce solo il payload.

400 restituisce un messaggio di ciò che era sbagliato nella richiesta:

{"message" : "Missing parameter: 'param'"}

Ritorno 404 se il modello / controler / URI non esiste

Se si è verificato un errore durante l'elaborazione da parte mia, restituisco 501 con un messaggio:

{"message" : "Could not connect to data store."}

Da quello che ho visto alcuni framework REST tendono a seguire questa linea.

Fondamento logico :

JSON dovrebbe essere un formato di payload , non è un protocollo di sessione. L'intera idea di payload dettagliati di sessione proviene dal mondo XML / SOAP e da varie scelte sbagliate che hanno creato quei disegni gonfiati. Dopo che ci siamo resi conto che si trattava di un forte mal di testa, il punto cruciale di REST / JSON era di KISS e aderire a HTTP. Non credo che ci sia qualcosa di lontanamente di serie in entrambi i JSend e soprattutto non con il più dettagliato tra di loro. XHR reagirà alla risposta HTTP, se si utilizza jQuery per AJAX (come la maggior parte fa), è possibile utilizzare try/ catche done()/ fail()callback per acquisire errori. Non riesco a vedere come l'incapsulamento dei rapporti sullo stato in JSON sia più utile di così.

Per quello che vale, lo faccio diversamente. Una chiamata riuscita ha solo gli oggetti JSON. Non ho bisogno di un oggetto JSON di livello superiore che contenga un campo di successo che indica true e un campo payload con l'oggetto JSON. Restituisco l'oggetto JSON appropriato con un 200 o qualsiasi cosa sia appropriata nell'intervallo 200 per lo stato HTTP nell'intestazione.

Tuttavia, se c'è un errore (qualcosa nella famiglia 400) restituisco un oggetto errore JSON ben formato. Ad esempio, se il client sta postando un utente con un indirizzo e-mail e un numero di telefono e uno di questi è malformato (cioè non riesco a inserirlo nel mio database sottostante) restituirò qualcosa del genere:

{
  "description" : "Validation Failed"
  "errors" : [ {
    "field" : "phoneNumber",
    "message" : "Invalid phone number."
  } ],
}

I bit importanti qui sono che la proprietà "field" deve corrispondere esattamente al campo JSON che non può essere validato. Ciò consente ai clienti di sapere esattamente cosa è andato storto nella loro richiesta. Inoltre, "messaggio" si trova nelle impostazioni internazionali della richiesta. Se sia "emailAddress" che "phoneNumber" non fossero validi, l'array "errori" conterrebbe voci per entrambi. Un corpo di risposta JSON 409 (conflitto) potrebbe essere simile al seguente:

{
  "description" : "Already Exists"
  "errors" : [ {
    "field" : "phoneNumber",
    "message" : "Phone number already exists for another user."
  } ],
}

Con il codice di stato HTTP e questo JSON il client ha tutto ciò di cui ha bisogno per rispondere agli errori in modo deterministico e non crea un nuovo standard di errore che tenta di completare la sostituzione dei codici di stato HTTP. Nota, questi si verificano solo per l'intervallo di 400 errori. Per qualsiasi cosa nella gamma 200 posso semplicemente restituire ciò che è appropriato. Per me è spesso un oggetto JSON simile a HAL ma qui non importa davvero.

L'unica cosa che ho pensato di aggiungere era un codice numerico di errore nelle voci dell'array "errori" o nella radice dell'oggetto JSON stesso. Ma finora non ne abbiamo avuto bisogno.

Il loro non è d'accordo sui restanti formati di risposta API dei grandi giganti del software - Google, Facebook, Twitter, Amazon e altri, sebbene molti collegamenti siano stati forniti nelle risposte sopra, in cui alcune persone hanno cercato di standardizzare il formato di risposta.

Poiché le esigenze delle API possono variare, è molto difficile coinvolgere tutti e concordare un determinato formato. Se hai milioni di utenti che utilizzano la tua API, perché dovresti cambiare il formato di risposta?

Di seguito è la mia opinione sul formato di risposta ispirato a Google, Twitter, Amazon e alcuni post su Internet:

https://github.com/adnan-kamili/rest-api-response-format

File Swagger:

https://github.com/adnan-kamili/swagger-sample-template

Il punto di JSON è che è completamente dinamico e flessibile. Piegalo a qualsiasi capriccio che desideri, perché è solo un insieme di oggetti e array JavaScript serializzati, radicati in un singolo nodo.

Quale sia il tipo di rootnode dipende da te, cosa contiene dipende da te, se invii metadati insieme alla risposta dipende da te, se imposti il ​​tipo mime application/jsono lo lasci come text/plaindipende da te ( purché tu sappia come gestire i casi limite).

Crea uno schema leggero che ti piace.
Personalmente, ho scoperto che il tracciamento analitico e il servizio mp3 / ogg e il servizio di gallerie di immagini e messaggi di testo e pacchetti di rete per giochi online, e post di blog e commenti di blog hanno tutti requisiti molto diversi in termini di ciò che è inviato e cosa viene ricevuto e come dovrebbero essere consumati.

Quindi l'ultima cosa che vorrei fare, quando faccio tutto questo, è provare a rendere ognuno conforme allo stesso standard di plateplate, che si basa su XML2.0 o somesuch.

Detto questo, c'è molto da dire sull'uso di schemi che hanno senso per te e sono ben pensati.
Basta leggere alcune risposte API, annotare ciò che ti piace, criticare ciò che non ti piace, scrivere quelle critiche e capire perché ti strofinano nel modo sbagliato, quindi pensa a come applicare ciò che hai imparato a ciò di cui hai bisogno.

JSON-RPC 2.0 definisce un formato di richiesta e risposta standard ed è una boccata d'aria fresca dopo aver lavorato con le API REST.

Per quelli che verranno dopo, oltre alla risposta accettata che include HAL, JSend e JSON API, aggiungerei alcune altre specifiche che vale la pena esaminare:

• JSON-LD , che è una raccomandazione W3C e specifica come creare servizi Web interoperabili in JSON
• Ion Hypermedia Type for REST, che si afferma come "un tipo hypermedia JSON semplice e intuitivo per REST"

Il framework di base suggerito sembra a posto, ma l'oggetto errore come definito è troppo limitato. Spesso non è possibile utilizzare un singolo valore per esprimere il problema, e invece è necessaria una catena di problemi e cause .

Ho fatto una piccola ricerca e ho scoperto che il formato più comune per la restituzione dell'errore (eccezioni) è una struttura di questo modulo:

{
   "success": false,
   "error": {
      "code": "400",
      "message": "main error message here",
      "target": "approx what the error came from",
      "details": [
         {
            "code": "23-098a",
            "message": "Disk drive has frozen up again.  It needs to be replaced",
            "target": "not sure what the target is"
         }
      ],
      "innererror": {
         "trace": [ ... ],
         "context": [ ... ]
      }
   }
}

Questo è il formato proposto dallo standard di dati OASIS OASIS OData e sembra essere l'opzione più standard là fuori, tuttavia a questo punto non sembrano esserci alti tassi di adozione di alcuno standard. Questo formato è coerente con le specifiche JSON-RPC.

Puoi trovare la libreria open source completa che lo implementa su: Mendocino JSON Utilities . Questa libreria supporta gli oggetti JSON e le eccezioni.

I dettagli sono discussi nel mio post sul blog sulla gestione degli errori nell'API REST JSON

Non esiste uno standard di violazione della legge o fuorilegge diverso dal buon senso. Se astraggiamo questo come due persone che parlano, lo standard è il modo migliore in cui possono capirsi con precisione in parole minime in un tempo minimo. Nel nostro caso, "parole minime" sta ottimizzando la larghezza di banda per l'efficienza del trasporto e "comprendere accuratamente" è la struttura per l'efficienza del parser; che alla fine finisce con meno dati e comune la struttura; in modo che possa passare attraverso un foro e può essere analizzato attraverso un ambito comune (almeno inizialmente).

Quasi in tutti i casi suggeriti, vedo risposte separate per lo scenario "Successo" e "Errore", il che è una specie di ambiguità per me. Se le risposte sono diverse in questi due casi, allora perché abbiamo davvero bisogno di mettere un flag "Successo" lì? Non è ovvio che l'assenza di "Errore" è un "Successo"? È possibile avere una risposta in cui "Successo" è VERO con un "Errore" impostato? Oppure, "Successo" è FALSO senza "Errore" impostato? Una sola bandiera non è abbastanza? Preferirei avere solo il flag "Errore", perché credo che ci sarà meno "Errore" rispetto a "Successo".

Inoltre, dovremmo davvero rendere "Errore" una bandiera? E se volessi rispondere con più errori di validazione? Quindi, trovo più efficiente avere un nodo 'Errore' con ogni errore come figlio di quel nodo; dove un nodo "Errore" vuoto (conta fino a zero) indicherebbe un "Successo".

Migliore risposta per le API Web che possono essere facilmente comprese dagli sviluppatori di dispositivi mobili.

Questo è per la risposta "Success"

{  
   "ReturnCode":"1",
   "ReturnMsg":"Successfull Transaction",
   "ReturnValue":"",
   "Data":{  
      "EmployeeName":"Admin",
      "EmployeeID":1
   }
}

Questo è per la risposta "Errore"

{
    "ReturnCode": "4",
    "ReturnMsg": "Invalid Username and Password",
    "ReturnValue": "",
    "Data": {}
}