JSON-RPC - JSON-RPC

JSON-RPC è un protocollo di chiamata a procedura remota codificato in JSON . È simile al protocollo XML-RPC , definendo solo pochi tipi di dati e comandi. JSON-RPC consente l'invio di notifiche (dati inviati al server che non richiedono una risposta) e l'invio di più chiamate al server a cui è possibile rispondere in modo asincrono.

Storia

Versione Descrizione Datato
1.0 Versione originale 2005
1.1 WD Bozza funzionante . Aggiunge parametri denominati, aggiunge codici di errore specifici e aggiunge funzioni di introspezione. 2006-08-07
1.1 Alt Suggerimento per un semplice JSON-RPC 1.1 . Proposta alternativa alla 1.1 WD. 2007-05-06
1.1 Specifiche dell'oggetto Specificazione dell'oggetto . Proposta alternativa alla 1.1 WD/1.1ALT. 2007-07-30
1.2 Proposta . Una revisione successiva di questo documento è stata rinominata 2.0. 2007-12-27
2.0 Proposta di specifica 2009-05-24
2.0 (rivisto-) Specifiche 2010-03-26

Utilizzo

JSON-RPC funziona inviando una richiesta a un server che implementa questo protocollo. Il client in quel caso è tipicamente un software che intende chiamare un singolo metodo di un sistema remoto. È possibile passare più parametri di input al metodo remoto come array o oggetto, mentre il metodo stesso può restituire anche più dati di output. (Dipende dalla versione implementata.)

Tutti i tipi di trasferimento sono oggetti singoli, serializzati tramite JSON. Una richiesta è una chiamata a un metodo specifico fornito da un sistema remoto. Può contenere tre membri:

  • method- Una Stringa con il nome del metodo da invocare. Nomi dei metodi che iniziano con "rpc". sono riservati ai metodi rpc-internal.
  • params- Un oggetto o un array di valori da passare come parametri al metodo definito. Questo membro può essere omesso.
  • id- Una stringa o un numero non frazionario utilizzato per abbinare la risposta alla richiesta a cui si sta rispondendo. Questo membro può essere omesso se non deve essere restituita alcuna risposta.

Il destinatario della richiesta deve rispondere con una risposta valida a tutte le richieste ricevute. Una risposta può contenere i membri menzionati di seguito.

  • result- I dati restituiti dal metodo invocato. Questo elemento è formattato come oggetto JSON-stat. Se si è verificato un errore durante il richiamo del metodo, questo membro non deve esistere.
  • error- Un oggetto errore se si è verificato un errore durante l'invocazione del metodo, altrimenti questo membro non deve esistere. L'oggetto deve contenere il codice dei membri (intero) e il messaggio (stringa). Un membro dati facoltativo può contenere ulteriori dati specifici del server. Esistono codici di errore predefiniti che seguono quelli definiti per XML-RPC.
  • id - L'id della richiesta a cui sta rispondendo.

Poiché ci sono situazioni in cui non è necessaria o addirittura desiderata alcuna risposta, sono state introdotte le notifiche. Una notifica è simile a una richiesta ad eccezione dell'id, che non è necessario perché non verrà restituita alcuna risposta. In questo caso la idproprietà deve essere omessa (Versione 2.0) o essere null(Versione 1.0).

Esempi

In questi esempi, -->indica i dati inviati a un servizio ( richiesta ), mentre <--indica i dati provenienti da un servizio. Sebbene <--sia spesso chiamata risposta nell'elaborazione client-server, a seconda della versione JSON-RPC non implica necessariamente una risposta a una richiesta .

Versione 2.0

Richiesta e risposta: 

--> {"jsonrpc": "2.0", "method": "subtract", "params": {"minuend": 42, "subtrahend": 23}, "id": 3}
<-- {"jsonrpc": "2.0", "result": 19, "id": 3}

Notifica (nessuna risposta): 

--> {"jsonrpc": "2.0", "method": "update", "params": [1,2,3,4,5]}

Versione 1.1 (Bozza di lavoro)

Richiesta e risposta: 

--> {"version": "1.1", "method": "confirmFruitPurchase", "params": [["apple", "orange", "mangoes"], 1.123], "id": "194521489"}
<-- {"version": "1.1", "result": "done", "error": null, "id": "194521489"}

Versione 1.0

Richiesta e risposta: 

--> {"method": "echo", "params": ["Hello JSON-RPC"], "id": 1}
<-- {"result": "Hello JSON-RPC", "error": null, "id": 1}

Guarda anche

Riferimenti

  1. ^ "specifica - JSON-RPC - Trac" . Archiviato dall'originale il 17/05/2008 . Estratto il 14/05/2008 .
  2. ^ "Specifiche JSON-RPC 2.0" . id: un identificatore stabilito dal cliente che DEVE contenere una stringa, un numero o un valore NULL se incluso. Se non è incluso, si presume che sia una notifica. Il valore normalmente NON DOVREBBE essere Null e i numeri NON DOVREBBE contenere parti frazionarie
  3. ^ "Specifiche JSON-RPC 2.0" . Una notifica è un oggetto Request senza un membro "id". Un oggetto Richiesta che è una Notifica indica la mancanza di interesse del Cliente per l'oggetto Risposta corrispondente e, in quanto tale, nessun oggetto Risposta deve essere restituito al cliente. Il server NON DEVE rispondere a una notifica, comprese quelle che si trovano all'interno di una richiesta batch. Le notifiche non sono confermabili per definizione, poiché non hanno un oggetto Response da restituire. In quanto tale, il Cliente non sarebbe a conoscenza di eventuali errori (come ad esempio "Parametri non validi", "Errore interno").
  4. ^ "Specifiche JSON-RPC 2.0" . risultato: questo membro è OBBLIGATORIO in caso di successo. Questo membro NON DEVE esistere se si è verificato un errore durante l'invocazione del metodo. Il valore di questo membro è determinato dal metodo invocato sul Server.
  5. ^ "Specifiche JSON-RPC 2.0" . errore: questo membro è OBBLIGATORIO in caso di errore. Questo membro NON DEVE esistere se non si sono verificati errori durante l'invocazione. Il valore per questo membro DEVE essere un oggetto come definito nella sezione 5.1.
  6. ^ "Specifiche JSON-RPC 2.0" . Oggetto errore: quando una chiamata rpc incontra un errore, l'oggetto risposta DEVE contenere il membro errore con un valore che è un oggetto con i seguenti membri: (codice) - Un numero che indica il tipo di errore che si è verificato. Questo DEVE essere un numero intero. (messaggio) - Una stringa che fornisce una breve descrizione dell'errore. Il messaggio DOVREBBE essere limitato a una singola frase concisa. (dati) - Un valore primitivo o strutturato che contiene informazioni aggiuntive sull'errore. Questo può essere omesso. Il valore di questo membro è definito dal server (ad es. informazioni dettagliate sull'errore, errori nidificati, ecc.).

link esterno