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
}
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.
Pomocí JSON-RPC rozhraní jsou zveřejněny tyto metody:
menu_list)category_list, category_list_nullstream)item_detail)item_consume)item_order)cancel_order)library)list_flags)list_states)list_types)Následující seznam metod a jejich popis je orientační. Aktuální seznam metod a jejich nápověda se nachází na rozhraní.
Všechny metody vyžadují parametr distributor_key, pomocí kterého idenfikujeme distributora.
Seznam dostupných kategorií je možné vypsat voláním metody menu_list. Kategorie mají stromovou strukturu. Jedna položka může být ve více kategoriích.
Katalog obsahu je možné získat buďto volánín metody category_list se stránkováním, nebo pomocí speciální metody category_list_nullstream, která vrátí všechny položky dle zvoleného filtru, ale jako sérii JSON struktur pro detail položky oddělených nullbytem \00. Parametry volání pro nullstream jsou stejné, jako pro category_list, pouze volání vždy vrátí všechna data. Jedná se o speciální volání, které vrací dlouhy stream, odpověď tedy nebude obsahovat klíče status a status_message a HTTP odpověď nebude obsahovat hlavičku Content-Length. Klasické listování položek v kategorii vrací základní metadata potřebná pro výpis seznamu položek, nicméně varianta nullstream vrací řadu kompletních detailů.
V případě zrcadlení (využívání metody nullstream) jsou vracen i ty položky, které byly odebrané z distribuce. Takové položky by si měl distributor odstranit z vlastní databáze.
Aby nebylo nutné updatovat vždy kompletní katalog, je tu několik možností jak omezit výsledky (pokud je provider podporuje). Nastavení parametru last_id vrátí produkty jejichž id je větší než zadané. Filtr last_update omezí výsledek na produkty updatované po zadaném čase.
Aby uživatel mohl získat požadovaný obsah, je potřeba nejprve založit objednávku a to ve chvíli, kdy si uživatel danou položku zakoupí. Je to důležité zejména pro reporting a pro počítání ceny ve chvíli, kdy byla položka zaplacená. K objednávce je potřeba poslat cenu, za kterou byla položka prodána. Návratová hodnota volání objednávky pak je jednoznačný identifikátor objednávky. K založení objednávky je navíc potřeba poslat identifikátor uživatele.
Vytvořením objednávky se uživateli automaticky vytváří jeho knihovna. Knihovnu je možné používat buďto přímo pro listování obsahu, který si uživatel zakoupil, nebo pro účely helpdesku.
Aby se uživatel dostal k obsahu je potřeba založit download request s identifikátorem objednávky, se kterým byla daná položka objednána.
Pro případ reklamací umožňuje rozhraní objednávku zrušit.