Panoramica
JSON-RPC è un protocollo di chiamata di procedura remota (RPC) senza stato e leggero. Questa specifica definisce principalmente diverse strutture di dati e le regole per la loro elaborazione. È agnostico rispetto al trasporto, in quanto i concetti possono essere utilizzati all'interno dello stesso processo, su socket, su http o in molti altri ambienti di trasmissione di messaggi. Utilizza JSON (RFC 4627) come formato dati.
È stato progettato per essere semplice!
Convenzioni
Le parole chiave "DEVE / DEVONO", "NON DEVE / NON DEVONO", "RICHIESTO", "DOVRÀ / DOVRANNO", "NON DOVRÀ / NON DOVRANNO", "DOVREBBE / DOVREBBERO", "NON DOVREBBE / NON DOVREBBERO", "CONSIGLIATO", "PUÒ . POSSONO", "NON PUÒ / NON POSSONO", "OBBLIGATORIO" e "FACOLTATIVO" utilizzate in questo documento devono essere interpretate come descritto in RFC 2119.
Dato che JSON-RPC utilizza JSON, ha lo stesso sistema di tipi di ati (consultare la pagina http://www.json.org o RFC 4627).
JSON può rappresentare quattro tipi di dati primitivi (Stringa, Numero, Elemento booleano e Null) e due tipi strutturati (Oggetto e Array). In questa specifica, il termine "primitivo" si riferisce a uno qualsiasi di questi quattro tipi primitivi di JSON. Il termine "strutturato" si riferisce a uno qualsiasi dei tipi JSON strutturati. Ogni volta che in questo documento si fa riferimento a un tipo JSON, la prima lettera è sempre maiuscola: Oggetto , Array, Stringa, Numero, Elemento booleano e Null. Anche Vero e Falso sono maiuscoli.
Tutti i nomi dei membri scambiati tra il client e il server, considerati per qualsiasi tipo di comunicazione, fanno distinzione tra maiuscole e minuscole. I termini funzione, metodo e procedura possono essere considerati intercambiabili.
Il client è definito come l'origine degli oggetti Richiesta e il gestore degli oggetti Risposta.
Il server è definito come l'origine degli oggetti Richiesta e il gestore degli oggetti Risposta.
Un'implementazione di questa specifica potrebbe facilmente ricoprire entrambi i ruoli, anche contemporaneamente, per altri client diversi o per lo stesso client. Questa specifica non affronta questo livello di complessità.
Compatibilità
Gli oggetti Richiesta e Risposta di JSON-RPC 2.0 potrebbero non funzionare con i client o i server JSON-RPC 1.0 esistenti. Tuttavia, è facile distinguere tra le due versioni, poiché la versione 2.0 ha sempre un membro chiamato "jsonrpc" con un valore Stringa di "2.0", mentre la 1.0 non lo possiede. La maggior parte delle implementazioni della versione 2.0 dovrebbero prendere in considerazione la possibilità di gestire gli oggetti della versione 1.0, anche se non gli aspetti peer-to-peer e di suggerimento delle classi della versione 1.0.
Oggetto richiesta
Una chiamata rpc viene implementata inviando un oggetto Richiesta a un Server. L'oggetto Richiesta ha i seguenti membri:
jsonrpc - Una Stringa che specifica la versione del protocollo JSON-RPC. DEVE avere esattamente il valore "2.0".
method - Una Stringa contenente il nome del metodo da invocare. I nomi dei metodi che iniziano con la parola rpc seguita da un punto (carattere U+002E o ASCII 46) sono riservati ai metodi interni alla rpc e alle estensioni e NON POSSONO essere usati per altro.
params - Un valore strutturato che contiene i valori dei parametri da utilizzare durante l'invocazione del metodo. PUÒ essere omesso.
id -Un identificatore stabilito dal client che DEVE contenere una Stringa, un Numero o un valore Null se incluso. Se non è incluso, si presume che sia una notifica. Il valore NON DOVREBBE normalmente essere Null [1] e i numeri NON DOVREBBERO contenere parti frazionarie [2].
Il server DEVE rispondere con lo stesso valore nell'oggetto Risposta, se incluso. Questo membro viene utilizzato per correlare il contesto tra i due oggetti.
[1] L'uso di Null come valore per il membro id in un oggetto Richiesta è sconsigliato, perché questa specifica usa un valore Null per le risposte con un id sconosciuto. Inoltre, poiché JSON-RPC 1.0 utilizza un valore id di Null per le notifiche, ciò potrebbe causare confusione nella gestione.
[2] Le parti frazionarie possono rappresentare un problema, poiché molte frazioni decimali non possono essere convertite esattamente in frazioni binarie.
Notifica
Una Notifica è un oggetto Richiesta senza un membro "id". Un oggetto Richiesta che è una Notifica indica che il client non è interessato all'oggetto Risposta corrispondente e quindi non deve essere restituito alcun oggetto Risposta al client. 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 Risposta da restituire. In questo caso il client non viene a conoscenza di eventuali errori (ad esempio: "Invalid params" (Parametri non validi), "Internal error" (Errore interno)).
Strutture dei parametri
Se presenti, i parametri per la chiamata rpc DEVONO essere forniti come valore strutturato. O per posizione attraverso un Array o per nome attraverso un Oggetto.
-
per posizione: i parametri DEVONO essere Array, contenenti i valori nell'ordine previsto dal server.
-
per nome: i parametri DEVONO essere un Oggetto, con nomi di membri che corrispondono ai nomi dei parametri attesi dal Server. L'assenza di nomi attesi PUÒ generare un errore. I nomi DEVONO corrispondere esattamente, incluse maiuscole e minuscole, ai parametri attesi del metodo.
Oggetto risposta
Quando viene effettuata una chiamata rpc, il server DEVE rispondere con una Risposta, tranne nel caso delle Notifiche. La risposta è espressa come singolo oggetto JSON, con i seguenti membri:
jsonrpc - Una Stringa che specifica la versione del protocollo JSON-RPC. DEVE assumere esattamente il valore "2.0".
result - Questo membro è OBBLIGATORIO in caso di successo.
Questo membro NON DEVE esistere se si è verificato un errore nell'invocazione del metodo.
Il valore di questo membro è determinato dal metodo invocato sul server.
error - Questo membro è OBBLIGATORIO in caso di errore.
Questo membro NON DEVE esistere se non si è verificato alcun errore durante l'invocazione.
Il valore di questo membro DEVE essere un Oggetto come definito nella sezione 5.1.
id - Questo membro è OBBLIGATORIO.
DEVE essere uguale al valore del membro id nell'oggetto Richiesta.
Se c'è stato un errore nel rilevare l'id nell'oggetto Richiesta (ad esempio, errore di parsing o richiesta non valida), DEVE essere Null.
DEVE essere incluso il membro result o il membro error, ma NON entrambi.
Oggetto errore
Quando a seguito di una chiamata rpc si verifica un errore, l'oggetto Risposta DEVE contenere il membro error con un valore che è un Oggetto con i seguenti membri:
code - Un numero che indica il tipo di errore che si è verificato.
DEVE essere un numero intero.
message - A String providing a short description of the error.
The message SHOULD be limited to a concise single sentence.
data - Un tipo primitivo o strutturato che contiene informazioni aggiuntive sull'errore.
Può non essere presente.
Il valore di questo membro è definito dal server (ad esempio, informazioni dettagliate sugli errori, errori annidati ecc.)
I codici di errore compresi tra -32768 e -32000 sono riservati agli errori predefiniti. Qualsiasi codice all'interno di questo intervallo, e non definito esplicitamente di seguito, è riservato per usi futuri. I codici di errore sono quasi identici a quelli suggeriti per XML-RPC che si possono trovare alla pagina: http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php
| code (codice) | message (messagio) | significato |
|---|---|---|
| -32700 | Parse error (Errore di parsing) | Il server ha ricevuto un JSON non valido. Si è verificato un errore sul server durante il parsing del testo JSON. |
| -32600 | Invalid Request (Richiesta non valida) | Il JSON inviato non è un oggetto valido della richiesta. |
| -32601 | Method not found (Metodo non trovato) | Il metodo non esiste o non è disponibile. |
| -32602 | Invalid params (Parametri non validi) | Parametri del metodo non validi. |
| -32603 | Internal error (Errore interno) | Errore interno JSON-RPC. |
| da -32099 a -32000 | Server error (Errore del server) | Riservati agli errori del server definiti dall'implementazione. |
Il resto dello spazio è disponibile per gli errori applicativi.
Batch
Per inviare più oggetti Richiesta contemporaneamente, il client PUÒ inviare un Array pieno di oggetti Richiesta.
Il server DEVE rispondere con un array contenente gli oggetti Risposta corrispondenti, dopo che tutti gli oggetti Richiesta sono stati elaborati. DOVREBBE esistere un oggetto Risposta per ogni oggetto Richiesta, ad eccezione delle Notifiche; in questo caso NON DOVREBBE esistere alcun oggetto Risposta. Il server PUÒ elaborare una chiamata rpc batch come un insieme di task concorrenti, elaborandoli in qualsiasi ordine e con qualsiasi parallelismo.
Gli oggetti Risposta restituiti da una chiamata batch POSSONO essere restituiti in qualsiasi ordine all'interno dell'array. Il client DOVREBBE abbinare i contesti tra l'insieme di oggetti Richiesta e l'insieme risultante di oggetti Risposta in base al membro id di ciascun Oggetto.
Se la chiamata rpc batch non viene riconosciuta come un JSON valido o come un Array con almeno un valore, la risposta del server DEVE essere un singolo oggetto Risposta. Se non ci sono oggetti Risposta contenuti nell'array da inviare al client, il server NON DEVE restituire un array vuoto: non dovrebbe restituire nulla.
Esempi
Sintassi:
--> data sent to Server <-- data sent to Client
chiamata rpc con parametri posizionali:
--> {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}
<-- {"jsonrpc": "2.0", "result": 19, "id": 1}
--> {"jsonrpc": "2.0", "method": "subtract", "params": [23, 42], "id": 2}
<-- {"jsonrpc": "2.0", "result": -19, "id": 2}
chiamata rpc con parametri denominati:
--> {"jsonrpc": "2.0", "method": "subtract", "params": {"subtrahend": 23, "minuend": 42}, "id": 3}
<-- {"jsonrpc": "2.0", "result": 19, "id": 3}
--> {"jsonrpc": "2.0", "method": "subtract", "params": {"minuend": 42, "subtrahend": 23}, "id": 4}
<-- {"jsonrpc": "2.0", "result": 19, "id": 4}
notifica:
--> {"jsonrpc": "2.0", "method": "update", "params": [1,2,3,4,5]}
--> {"jsonrpc": "2.0", "method": "foobar"}
chiamata rpc di un metodo inesistente:
--> {"jsonrpc": "2.0", "method": "foobar", "id": "1"}
<-- {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Procedure not found."}, "id": "1"}
chiamata rpc con JSON non valido:
--> {"jsonrpc": "2.0", "method": "foobar, "params": "bar", "baz]
<-- {"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error."}, "id": null}
chiamata rpc con oggetto richiesta non valida:
--> {"jsonrpc": "2.0", "method": 1, "params": "bar"}
<-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null}
chiamta rpc Batch, JSON non valido:
--> [ {"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},{"jsonrpc": "2.0", "method" ]
<-- {"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error."}, "id": null}
chiamata rpc con un Array vuoto:
--> []
<-- "jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null}
chiamata rpc con un Batch non valido (ma non vuoto):
--> [1]
<-- [ {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null} ]
chiamata rpc con un Batch non valido:
--> [1,2,3]
<-- [
{"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null},
{"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null},
{"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null}
]
chiamata rpc Batch:
--> [
{"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},
{"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},
{"jsonrpc": "2.0", "method": "subtract", "params": [42,23], "id": "2"},
{"foo": "boo"},
{"jsonrpc": "2.0", "method": "foo.get", "params": {"name": "myself"}, "id": "5"},
{"jsonrpc": "2.0", "method": "get_data", "id": "9"}
]
<-- [
{"jsonrpc": "2.0", "result": 7, "id": "1"},
{"jsonrpc": "2.0", "result": 19, "id": "2"},
{"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null},
{"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found."}, "id": "5"},
{"jsonrpc": "2.0", "result": ["hello", 5], "id": "9"}
]
chiamata rpc Batch (tutte le notifiche):
--> [
{"jsonrpc": "2.0", "method": "notify_sum", "params": [1,2,4]},
{"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},
]
<-- //Nothing is returned for all notification batches
Estensioni
I nomi dei metodi che iniziano con rpc. sono riservati alle estensioni di sistema e NON POSSONO essere usati per altro. Ogni estensione di sistema è definita in una specifica correlata. Tutte le estensioni di sistema sono OPZIONALI.
Copyright (C) 2007-2010 - JSON-RPC Working Group
Questo documento e le sue traduzioni possono essere utilizzati per implementare JSON-RPC, possono essere copiati e forniti ad altri, e le opere derivate che commentano o spiegano in altro modo il documento o aiutano nella sua implementazione possono essere preparate, copiate, pubblicate e distribuite, in tutto o in parte, senza restrizioni di alcun tipo, a condizione che l'avviso di copyright di cui sopra e il presente paragrafo siano inclusi in tutte le copie e opere derivate. Ciò detto, il presente documento non può essere modificato in alcun modo.
I permessi limitati concessi sopra sono perpetui e non saranno revocati.
Il presente documento e le informazioni in esso contenute sono fornite "COSÌ COME SONO" e TUTTE LE GARANZIE, ESPLICITE O IMPLICITE, SONO ESCLUSE, INCLUDENDO IN MODO SPECIFICO MA NON LIMITATO, QUALSIASI GARANZIA CHE L'USO DELLE INFORMAZIONI IN ESSO CONTENUTE NON VIOLI ALCUN DIRITTO O QUALSIASI GARANZIA IMPLICITA DI COMMERCIABILITÀ O IDONEITÀ PER UNO SCOPO PARTICOLARE.