GFI KerioConnect® – Specifiche JSON-RPC 2.0

Panoramica

JSON-RPC è un protocollo RPC (Remote Procedure Call) leggero e senza stato. Questa specifica definisce principalmente diverse strutture di dati e le regole relative alla loro elaborazione. È indipendente dal protocollo di trasporto, in quanto i concetti in essa contenuti possono essere utilizzati all’interno dello stesso processo, tramite socket, tramite HTTP o in numerosi ambienti di passaggio di messaggi. Utilizza JSON (RFC 4627) come formato dei dati.

È stato progettato per essere semplice!

Convenzioni

I termini chiave “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY” e “OPTIONAL” presenti nel presente documento devono essere interpretati secondo quanto descritto nella RFC 2119.

Poiché JSON-RPC utilizza JSON, presenta lo stesso sistema di tipi (vedere http://www.json.org o RFC 4627). JSON può rappresentare quattro tipi primitivi (stringhe, numeri, valori booleani e null) e due tipi strutturati (oggetti e array). Il termine «primitivo» nella presente specifica si riferisce a uno qualsiasi di questi quattro tipi primitivi di JSON. Il termine «strutturato» si riferisce a uno qualsiasi dei tipi strutturati di JSON. Ogni volta che il presente documento fa riferimento a un tipo JSON, la prima lettera è sempre maiuscola: Oggetto, Array, Stringa, Numero, Booleano, Null. Anche True e False sono scritti con l’iniziale maiuscola.

Tutti i nomi dei membri scambiati tra il client e il server e presi in considerazione per qualsiasi tipo di corrispondenza devono essere considerati sensibili alle maiuscole e alle minuscole. I termini “funzione”, “metodo” e “procedura” possono essere considerati intercambiabili.

Il Client è definito come l'origine degli oggetti Request e il gestore degli oggetti Response.
Il Server è definito come l'origine degli oggetti Response e il gestore degli oggetti Request.

Un'implementazione della presente specifica potrebbe facilmente svolgere entrambi questi ruoli, anche contemporaneamente, per clienti diversi o per lo stesso cliente. La presente specifica non affronta tale livello di complessità.

Compatibilità

Gli oggetti Request e Response di JSON-RPC 2.0 potrebbero non funzionare con client o server JSON-RPC 1.0 esistenti. Tuttavia, è facile distinguere le due versioni poiché la versione 2.0 presenta sempre un membro denominato “jsonrpc” con valore String pari a “2.0”, mentre la versione 1.0 non lo possiede. La maggior parte delle implementazioni della versione 2.0 dovrebbe cercare di gestire gli oggetti della versione 1.0, anche se non gli aspetti relativi al peer-to-peer e al class hinting della versione 1.0.

Oggetto richiesta

Una chiamata RPC consiste nell'invio di un oggetto Request a un server. L'oggetto Request presenta i seguenti membri:

jsonrpc – Una stringa che specifica la versione del protocollo JSON-RPC. DEVE essere esattamente “2.0”.

metodo – Una stringa contenente il nome del metodo da invocare. I nomi dei metodi che iniziano con la parola "rpc" seguita da un punto (U+002E o ASCII 46) sono riservati ai metodi e alle estensioni interne a RPC e NON DEVONO essere utilizzati per nessun altro scopo.

params – Un valore strutturato che contiene i valori dei parametri da utilizzare durante l'invocazione del metodo. Questo membro PUÒ essere omesso.

id - Un identificatore definito dal Cliente che DEVE contenere una stringa, un numero o il valore NULL, se presente. Se non è presente, si presume che si tratti di una notifica. Il valore normalmente NON DOVREBBE essere nullo [1] e i numeri NON DOVREBBERO contenere parti frazionarie [2]

Il server DEVE rispondere con lo stesso valore nell'oggetto Response, se presente. Questo membro viene utilizzato per correlare il contesto tra i due oggetti.

[1] Si sconsiglia di utilizzare Null come valore per il membro id in un oggetto Request, poiché la presente specifica utilizza il valore Null per le risposte con un id sconosciuto. Inoltre, poiché JSON-RPC 1.0 utilizza il valore Null per l'id delle notifiche, ciò potrebbe causare confusione nella gestione.

[2] Le parti frazionarie possono rappresentare un problema, poiché molte frazioni decimali non possono essere rappresentate esattamente come frazioni binarie.

Notifica

Una Notifica è un oggetto Request privo del membro “id”. Un oggetto Request che è una Notifica indica la mancanza di interesse da parte del Client per il corrispondente oggetto Response e, pertanto, non è necessario restituire alcun oggetto Response al client. Il Server NON DEVE rispondere a una Notifica, comprese quelle contenute in una richiesta batch.

Le notifiche, per definizione, non possono essere confermate, poiché non prevedono la restituzione di un oggetto Response. Di conseguenza, il client non verrebbe a conoscenza di eventuali errori (come ad esempio “Parametri non validi” o “Errore interno”).

Strutture dei parametri

Se presenti, i parametri per la chiamata RPC DEVONO essere forniti come valore strutturato, sia per posizione tramite un array, sia per nome tramite un oggetto.

• by-position: i parametri DEVONO essere un array, contenente i valori nell'ordine previsto dal server.
• per nome: i parametri DEVONO essere un oggetto, con nomi dei membri che corrispondano ai nomi dei parametri previsti dal server. L'assenza dei nomi previsti POTREBBE causare la generazione di un errore. I nomi DEVONO corrispondere esattamente, anche per quanto riguarda le maiuscole e le minuscole, ai parametri previsti dal metodo.

Oggetto di risposta

Quando viene effettuata una chiamata RPC, il server DEVE rispondere con una risposta, salvo nel caso delle notifiche. La risposta è rappresentata da un singolo oggetto JSON, con i seguenti elementi:

jsonrpc – Una stringa che specifica la versione del protocollo JSON-RPC. DEVE essere esattamente “2.0”.

risultato – Questo membro è OBBLIGATORIO in caso di esito positivo.
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.

errore – Questo membro è OBBLIGATORIO in caso di errore.
Questo membro NON DEVE esistere se durante l'invocazione non si è verificato alcun errore.
Il valore di questo membro DEVE essere un oggetto.

id – Questo membro è OBBLIGATORIO.
DEVE corrispondere al valore del membro id nell'oggetto Request.
Se si è verificato un errore nel rilevamento dell'id nell'oggetto Request (ad es. errore di analisi/richiesta non valida), DEVE essere Null.

È NECESSARIO includere o il membro "result" o il membro "error", ma NON È CONSENTITO includere entrambi i membri.

Oggetto di errore

Quando una chiamata RPC rileva un errore, l'oggetto Response DEVE contenere il membro "error" con un valore che è un oggetto dotato dei seguenti membri:

codice – Un numero che indica il tipo di errore verificatosi.
Deve trattarsi di un numero intero.

messaggio – Una stringa che fornisce una breve descrizione dell'errore.
Il messaggio DOVREBBE limitarsi a una singola frase concisa.

data – Un valore primitivo o strutturato che contiene ulteriori informazioni sull'errore.
Questo elemento può essere omesso.
Il valore di questo membro è definito dal server (ad es. informazioni dettagliate sull'errore, errori annidati, ecc.).

I codici di errore compresi tra -32768 e -32000, inclusi, sono riservati a errori predefiniti. Qualsiasi codice compreso in questo intervallo, ma non definito esplicitamente di seguito, è riservato per un uso futuro. I codici di errore sono pressoché identici a quelli suggeriti per XML-RPC al seguente URL: http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php

Il resto dello spazio è riservato agli errori definiti dall'applicazione.

Lotto

Per inviare più oggetti Request contemporaneamente, il client PUÒ inviare un array contenente oggetti Request.

Il server dovrebbe rispondere con un array contenente gli oggetti Response corrispondenti, dopo che tutti gli oggetti Request del batch sono stati elaborati. Dovrebbe esserci un oggetto Response per ogni oggetto Request, salvo che NON dovrebbero esserci oggetti Response per le notifiche. Il server può elaborare una chiamata RPC in batch come un insieme di attività concorrenti, elaborandole in qualsiasi ordine e con qualsiasi grado di parallelismo.

Gli oggetti Response restituiti da una chiamata batch POSSONO essere restituiti in qualsiasi ordine all'interno dell'array. Il client DOVREBBE associare i contesti tra l'insieme degli oggetti Request e l'insieme risultante degli oggetti Response in base al membro id presente in ciascun oggetto.

Se la chiamata RPC in batch non viene riconosciuta come JSON valido o come array contenente almeno un valore, la risposta del server DEVE essere un singolo oggetto Response. Se l'array Response, così come deve essere inviato al client, non contiene alcun oggetto Response, il server NON DEVE restituire un array vuoto e non deve restituire alcuna risposta.

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}

Una 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 Request non valido:

--> {"jsonrpc": "2.0", "method": 1, "params": "bar"}
<-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null}

Chiamata 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 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 in 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 in 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 DEVONO essere utilizzati per nessun altro scopo. Ciascuna estensione di sistema è definita in una specifica corrispondente. Tutte le estensioni di sistema sono FACOLTATIVE.

Copyright (C) 2007-2010 del Gruppo di lavoro JSON-RPC

Il presente documento e le relative traduzioni possono essere utilizzati per l'implementazione di JSON-RPC; possono essere copiati e forniti a terzi; inoltre, è possibile redigere, copiare, pubblicare e distribuire, in tutto o in parte e senza alcuna restrizione, opere derivate che lo commentino, lo spieghino in altro modo o ne facilitino l'implementazione, a condizione che la suddetta nota sul copyright e il presente paragrafo siano inclusi in tutte le copie e opere derivate. Tuttavia, il presente documento non può essere modificato in alcun modo.

Le autorizzazioni limitate concesse sopra sono a tempo indeterminato e non saranno revocate.

Il presente documento e le informazioni in esso contenute sono forniti “COSÌ COME SONO” e SI ESCLUDE QUALSIASI GARANZIA, ESPLICITA O IMPLICITA, INCLUSA, A TITOLO ESEMPLIFICATIVO MA NON ESAUSTIVO, QUALSIASI GARANZIA CHE L’UTILIZZO DELLE INFORMAZIONI QUI CONTENUTE NON VIOLI ALCUN DIRITTO O QUALSIASI GARANZIA IMPLICITA DI COMMERCIABILITÀ O IDONEITÀ PER UN PARTICOLARE SCOPO.