Naše JSON-RPC rozhraní myšlenkově vychází z XML-RPC, ale řeší některé jeho nedostatky pro jednodušší používání.
Název volané metody je cesta v URL, takže například volání metody items se zapíše jako /items.
Tento JSON-RPC server umožňuje volání metod několika způsoby:
_, _callback, nebo callback. Jakmile volání obsahu jeden z těchto parametrů, automaticky se odpovídá pomocí JSONP. Více o JSONP na Wikipedii.Content-Type: application/x-www-form-urlencoded.application/json, text/json, nebo text/plain pro JSON a application/bson pro BSON.Rozhraní odpovídá buďto JSONem, jebo BSONem a to podle HTTP hlavičky Accept. Výchozí formát odpovědi je JSON.
Odpověď vždy obsahuje objekt s klíči status a status_message. Status je číselný stav vyřízení volání podobný stavovým kódům HTTP, ale může se lišit tam, kde neexistuje odpovídající HTTP status. Status_message pak obsahuje textový popis výsledku volání. V případě úspěšného volání je odpověď {“status”:200, “status_message”: “OK”}.
Pokud volání vrací nějaká data, kořenový objekt obsahuje ještě klíč s názvem volané metody.
GET /system_list_methods HTTP/1.0
User-Agent: curl/7.37.1
Host: dummy.grandit.cz:1200
Accept: */*
HTTP/1.1 200 OK
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, GET, OPTIONS
Access-Control-Allow-Headers: Reply-OK-Only
Connection: Close
Content-Length: __
{
"status_message": "OK",
"system_list_methods": [
"system_alive",
"system_list_methods",
"system_method_help",
"system_method_info",
"system_method_sig",
"system_multicall",
"system_status",
],
"status": 200
}
Server poskytuje několik systémových metod. Nejdůležitější jsou:
system_method_help - Vrátí nápovědu k dané metodě. Volá se jako /system_method_help?method=xxx.system_list_methods - Vrátí seznam metod dostupných na rozhraní.system_alive - Pro monitoring.system_method_info - Formátovaný jednoduchý textový popis metod - dají se přidat GET parametry html=1 případně devel=1.system_method_json_schema - Vrátí json-schema pro validaci dotazu.system_method_response_json_schema - Vrátí json-schema pro validaci odpovědi.Pokud do vstupního pole, zadáte adresu našeho RPC rozhraní, můžete klikem na tlačítko načíst jeho konfiguraci. S konfigurací rozhraní se načítají jak signatury metod, tak nápověda. Pomocí tohoto rozhraní je také možné jednotlivé metody provolat a zovnou se podívat na návratové hodnoty.