• Obecný popis rozhraní
  • Nápověda aplikace
  • Jak používat

Popis JSON-RPC

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.

Možnosti volání

Tento JSON-RPC server umožňuje volání metod několika způsoby:

  • HTTP GET - základní volání metody. Parametry metody se uvádějí jako GET parametry.
  • HTTP GET - JSONP - při volání z JS je možné použít JSONP, kde callback je možné uvést v parametru _, _callback, nebo callback. Jakmile volání obsahu jeden z těchto parametrů, automaticky se odpovídá pomocí JSONP. Více o JSONP na Wikipedii.
  • HTTP POST - parametry volání metody se posílají POSTem, jako hodnoty formuláře. Hodnoty poslané POSTem se zpracovávají, když přijdou s HTTP hlavičkou Content-Type: application/x-www-form-urlencoded.
  • HTTP POST JSON/BSON - parametry se předávání jako JSON/BSON objekt, kde klíče jsou parametry volání. Pro zpracování parametrů je potřeba posílat HTTP hlavičku application/json, text/json, nebo text/plain pro JSON a application/bson pro BSON.

Formát odpovědi

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.

Příklad:

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
}

Jak používat tento nástroj

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.

Vysvětlivky

Parametry

param
Povinný.
[param]
Volitelný.

Datové typy

any
Výběr z možností níže, pokud žádné nejsou, znamená opravdu cokoliv.
time
Standardní 24h formát času doplněný vždy na 2 místa. Vteřiny mohou mít desetinná místa (za tečkou), např. 13:01:15.4589.
datetime date
Textový řetězec ve formátu ISO-8601.
str
Textový řetězec.
int
Celé číslo neomezené délky.
float
Číslo s plovoucí desetinou čárkou s přeností na 15 desetinných míst.
decimal
Číslo s pevnou desetinou čárkou.
bool
Logické hodnoty True/False.
list
Uspořádaná posloupnost dat zapsaných pomocí hranatých závorek ([]) a čárek (,).
enum
Výčet symbolických jmen (členů) vázaných na unikátní hodnoty.
dict
Neuspořádaná sekvence dat, zapsaná pomocí složených závorek ({}), ve tvaru {klíč:hodnota}.
uuid
Univerzálně unikátní identifikátor, který je generován pomocí náhodných čísel. Verze 4.