JSON-WSP - JSON-WSP

JSON-WSP (JavaScript Object Notation Web-Service Protocol) je protokol webové služby, který používá JSON^[1] pro popis služby, požadavky a odpovědi. Je inspirován z JSON-RPC, ale nedostatek specifikace popisu služby s dokumentací v JSON-RPC vyvolal návrh JSON-WSP.

Formát popisu má pro JSON-WSP stejný účel jako WSDL má pro MÝDLO nebo IDL pro CORBA, což je popis typů a metod používaných v dané službě. Také popisuje vztahy mezi typy (tj. Vnořené typy) a definuje, jaké typy se očekávají jako argumenty metody a jaké typy může uživatel očekávat, že obdrží jako návratové hodnoty metody. Nakonec popis otevírá možnost přidat dokumentaci na úrovni služeb, metod, parametrů a návratů.

Komunikace mezi klienty a serverem JSON-WSP se provádí pomocí HTTP POŠTA^[2] požadavky a odpovědi s objekty JSON jako daty s aplikací / json typu obsahu.^[3]

Specifikace

JSON-WSP se skládá ze čtyř specifikací objektů JSON:

Specifikace	Popis
popis	Specifikace popisu služby (jako WSDL ). Tato specifikace popisuje metody, parametry metody, typy a návratové typy. Podporuje také uživatelskou dokumentaci na úrovni služeb, metod a parametrů.
žádost	Specifikace požadavků JSON. Obsahuje informace o metodě, která má být vyvolána, a všechny argumenty pro volání metody. Argumenty v požadavku se musí řídit definicí parametru stejné metody popsané v odpovídajícím popisu JSON-WSP.
Odezva	Specifikace pro odpovědi JSON. Objekt odpovědi obsahuje výsledek vyvolání metody služby. Návratový typ se musí řídit definovaným návratovým typem stejné metody v odpovídajícím popisu JSON-WSP.
chyba	Specifikace chybových odpovědí JSON. Poruchový objekt obsahuje chybový kód a chybový řetězec. Informace o chybě určuje, zda k chybě došlo na straně klienta nebo serveru. V závislosti na rámci služby na straně serveru lze extrahovat podrobnější informace, tj. Název souboru a číslo řádku, kde došlo k chybě.

POZNÁMKA: Specifikace JSON-WSP 1.0 je stále^{[když? ]} není konečné. Podívejte se na příklad z reálného světa v tomto článku, abyste získali představu o tom, jak bude specifikace strukturována. Aktuální stav aktuální specifikace je udržován na launchpad.net :.^[4] V současné době se vytváří návrh RFC a doufejme, že přijatý během několika měsíců.^{[když? ]}

Porozumění specifikační notaci

Stavební bloky

Pokud název definovaného stavebního bloku začíná na rx-, to znamená, že definice je a regulární výraz. V těchto definicích mají hranaté závorky roli definování třídy postav a závorky mají úlohu definovat skupiny zachycení.
Ve všech ostatních případech hranaté závorky notují seznamy a závorky notují buď rozhodnutí:^{[pravopis? ]}:
```
(d1 | d2 | ...)
```
opakování 0-mnoho:
```
( ... )*
```
opakování 1-mnoho:
```
( ... )+
```
nebo něco volitelného:
```
( ... )?
```

Společné stavební bloky

<rx-freetext> = ".*"<identifikátor rx> = "[a-zA-Z _] [a-zA-Z0-9 _] *"<rx-číslo> = [0-9]+<rx-boolean> = (true | false)<klíč> = <identifikátor rx><primitivní hodnota> = ( <rx-freetext> | <rx-číslo> | <rx-boolean> )<hodnota> = (    <primitivní hodnota> |    [ ( <hodnota>, )* ] |    { ( <klíč>: <hodnota>, )* } )<název metody> = <identifikátor rx><Název služby> = <identifikátor rx>

Popis objektové databáze

Další stavební bloky

<primitivní> = ("řetězec" | "číslo" | "float" | "příloha")<vyhledávač služeb> = <řetězec vyhovující rfc-1738><název typu> = <identifikátor rx><jméno člena> = <identifikátor rx><více typů> = ( <primitivní> | <název typu> | [<primitivní>] | [<název typu>] )<řetězec řetězce> = <rx-freetext><jméno param> = <identifikátor rx><def-order> = <rx-číslo><param-volitelný> = <rx-boolean>

Specifikace

{    "typ": „jsonwsp / description“,    "verze": "1.0",    "Název služby": <service-name>,    „url“: <service-locator>,    "typy": { (        : { (            : <multi-type> )+        } )*    },    "metody": { (        : {            „doc_lines“: [ ( <doc-string>, )* ],            „parametry“: { (                : {                    „doc_lines“: [ ( <doc-string>, )* ],                    "def_order": <def-order>,                    "typ": <multi-type>,                    "volitelný": <param-optional>                }, )*            },            „ret_info“: {                „doc_lines“: [ ( <doc-string>, )* ],                "typ": <multi-type>            }        } )+    }}

Popisy

:Adresa URL koncového bodu služby, která přijímá objekty požadavku JSON-WSP POST.

:Název služby rozlišuje velká a malá písmena. Identifikuje konkrétní službu vystavenou na konkrétním serveru.

doc_lines:Každý řetězec řetězce obsažený v seznamu doc_lines odráží jeden řádek dokumentace, který souvisí s nadřazeným objektem doc_lines.

Vyžádejte si objekt

Objekt požadavku obsahuje informace o tom, kterou metodu vyvolat a jaké argumenty vyvolat metodu. Rovněž ukládá informace o typu a verzi samotné.

Volitelné zrcadlo value lze použít k odeslání informací z klienta, které se pak serverem projeví a v nezměněném stavu se vrátí v objektu odpovědi odraz hodnota. Tato funkce umožňuje klientům odesílat více požadavků na metodu a odesílat hodnoty identifikace požadavku, které mohou být zachyceny obsluhou odpovědi klienta. To je z javascriptu často nutné, pokud server zpracovává více než jeden požadavek současně a klient nezná pořadí odpovědí.

Specifikace

{    "typ": „jsonwsp / požadavek“,    "verze": "1.0",    "název metody": <method-name>,    "args": { ( : , )* }(,    "zrcadlo": <value> )?}

Objekt odpovědi

Specifikace

The odraz value je nezměněný serverový odraz objektu požadavku zrcadlo hodnota. Je označen jako volitelný, protože je to klient, který prostřednictvím požadavku ovládá, zda je nebo není.

{    "typ": „jsonwsp / response“,    "verze": "1.0",    "Název služby": <service-name>,    "název metody": <method-name>,    "výsledek":  (,    "odraz": <value> )?}

Objekt reakce na poruchu

Další stavební bloky

<chybový kód> = ("nekompatibilní" | "klient" | "server")<řetězec závad> = <rx-freetext><chybový název souboru> = <rx-freetext><zlom-lineno> = <rx-číslo>

Specifikace

{    "typ": "jsonwsp / chyba",    "verze": "1.0",    "chyba": {        "kód": <fault-code>,        "tětiva": <fault-string>,        ("detail": [ ( <fault-string>, )* ] ,)?        ("název souboru": <fault-filename>,)?        ("lineno": <fault-lineno>,)?    }(,    "odraz": <value> )?}

Popisy

:Význam možných chybových kódů:

"nekompatibilní": Klientská verze JSON-WSP je nekompatibilní s verzí serveru JSON-WSP. Obvykle se setkáte s tímto typem chybového kódu, pokud existuje zásadní rozdíl mezi klientem a serverem.
"server": Došlo k chybě na straně serveru po úspěšném vyčerpání požadavku klienta.
"client": Požadavek klientů nemohl být serverem spotřebován kvůli nesprávnému formátu nebo chybějícím požadovaným argumentům atd.

Příklad ze skutečného světa

Popis

{    "typ": „jsonwsp / description“,    "verze": "1.0",    "Název služby": „UserService“,    „url“: „http://testladon.org:80/proxy.php?path=UserService/jsonwsp“,    "typy": {        "Skupina": {            „group_id“: "číslo",            "display_name": "tětiva",            "název": "tětiva",            „členové“: ["Uživatel"]        },        "Uživatel": {            „uživatelské jméno“: "tětiva",            "uživatelské ID": "číslo",            "mobilní, pohybliví": "tětiva",            "stáří": "číslo",            "křestní jméno": "tětiva",            "příjmení": "tětiva"        },        „CreateUserResponse“: {            "uživatelské ID": "číslo",            "úspěch": "booleovský"        }    },    "metody": {        „listUsers“: {            „doc_lines“: ["Seznam uživatelů, kteří mají uživatelské jméno, křestní jméno nebo příjmení, které odpovídá danému filtru."],            „parametry“: {                "name_filter": {                    "def_order": 1,                    „doc_lines“: ["Řetězec použitý k filtrování výsledného seznamu uživatelů."],                    "typ": "tětiva",                    "volitelný": Nepravdivé                }            },            „ret_info“: {                „doc_lines“: ["Seznam uživatelů."],                "typ": ["Uživatel"]            }        },        "listGroups": {            „doc_lines“: ["Seznam skupin, které mají název nebo zobrazovaný název odpovídající danému filtru."],            „parametry“: {                "name_filter": {                    "def_order": 1,                    „doc_lines“: ["Řetězec použitý k filtrování výsledného seznamu skupin."],                    "typ": "tětiva",                    "volitelný": Nepravdivé                }            },            „ret_info“: {                „doc_lines“: ["Seznam skupin."],                "typ": ["Skupina"]            }        },        "vytvořit uživatele": {            „doc_lines“: ["Vytvořit nový uživatelský účet."],            „parametry“: {                „uživatelské jméno“: {                    "def_order": 1,                    „doc_lines“: ["Jedinečné uživatelské jméno pro nový uživatelský účet."],                    "typ": "tětiva",                    "volitelný": Nepravdivé                },                "křestní jméno": {                    "def_order": 2,                    „doc_lines“: ["Jméno."],                    "typ": "tětiva",                    "volitelný": Nepravdivé                },                "příjmení": {                    "def_order": 3,                    „doc_lines“: ["Příjmení."],                    "typ": "tětiva",                    "volitelný": Nepravdivé                },                "mobilní, pohybliví": {                    "def_order": 4,                    „doc_lines“: ["Volitelné číslo mobilního telefonu."],                    "typ": "tětiva",                    "volitelný": skutečný                },                "stáří": {                    "def_order": 5,                    „doc_lines“: [„Volitelný věk osoby za účtem.“],                    "typ": "číslo",                    "volitelný": skutečný                }            },            „ret_info“: {                „doc_lines“: [],                "typ": „CreateUserResponse“            }        }    }}

Servisní volání 1

Žádost

{    "typ": „jsonwsp / požadavek“,    "verze": "1.0",    "název metody": "vytvořit uživatele",    "args": {        „uživatelské jméno“: "bettyw",        "křestní jméno": "Betty",        "příjmení": "Wilson",        "mobilní, pohybliví": "555-3423444"    },    "zrcadlo": {        „id“: 2    }}

Odezva

{    "typ": „jsonwsp / response“,    "verze": "1.0",    "Název služby": „UserService“,    "název metody": "vytvořit uživatele",    "výsledek": {        "uživatelské ID": 324,        "úspěch": skutečný    },    "odraz": {        „id“: 2    }}

Servisní hovor 2

Žádost

{    "typ": „jsonwsp / požadavek“,    "verze": "1.0",    "název metody": „listUsers“,    "args": {        "name_filter": "zvedák"    }}

Odezva

{    "typ": „jsonwsp / response“,    "verze": "1.0",    "Název služby": „UserService“,    "název metody": „listUsers“,    "výsledek": [{        „uživatelské jméno“: "jackp",        "uživatelské ID": 153,        "mobilní, pohybliví": "555-377843",        "stáří": 34,        "křestní jméno": "Zvedák",        "příjmení": "Petersen"    }, {        „uživatelské jméno“: "bradj",        "uživatelské ID": 321,        "mobilní, pohybliví": "555-437546",        "stáří": 27,        "křestní jméno": "Brad",        "příjmení": "Jackson"    }]}

Přílohy

The příloha typ je v JSON-WSP nový. Může být použit kdekoli v popisu jako primitivní typ. V požadavcích a odpovědích, které zahrnují přílohy, musí být formát zprávy vícedílný / související kde jsou přílohy přepravovány jako mimeparts typu média: aplikace / oktetový proud bez kódování přenosu obsahu (pouze raw binární). Mimeparts musí mít v záhlavích entit jedinečné ID OBSAHU. Hodnoty příloh v objektech požadavku / odpovědi JSON-WSP se musí shodovat s regulárním výrazem „^ cid: (. +) $“, Kde se skupina zachycení mapuje na jedno z CONTENT-ID mimepart.

Příklad popisu připojovací služby

Následující příklad ukazuje, jak může vypadat jednoduchý popis JSON-WSP s přílohami:

{    "typ": „jsonwsp / description“,    "verze": "1.0",    „url“: „http://mysite.com/TransferService/jsonwsp“,    "Název služby": „TransferService“,    "typy": {        "Soubor": {            "data": "příloha",            "název": "tětiva"        }    },    "metody": {        "nahrát": {            „ret_info“: {                „doc_lines“: [],                "typ": "číslo"            },            „doc_lines“: [],            „parametry“: {                "přicházející": {                    "def_order": 1,                    „doc_lines“: [],                    "typ": [ "Soubor" ],                    "volitelný": Nepravdivé                }            }        }    }}

Příklad požadavku na službu připojení

Výše popsaný požadavek na metodu „upload“ může vypadat takto:

Typ obsahu:vícedílný/příbuzný;hranice=„2676ff6efebdb664f8f7ccb34f864e25“--2676ff6efebdb664f8f7ccb34f864e25Typ obsahu:aplikace/JSON, znaková sada = UTF-8Content-ID: body{    "typ": „jsonwsp / požadavek“,    "verze": "1.0",    "název metody": "nahrát",    "args": {        "přicházející": [ {            "data": "cid: img2354.png",            "název": "face.png"        }, {            "data": „cid: cv.pdf“,            "název": "cv.pdf"        } ]    }}--2676ff6efebdb664f8f7ccb34f864e25Typ obsahu:aplikace/oktetový proudID obsahu: img2354.png<png-image binary data>--2676ff6efebdb664f8f7ccb34f864e25Typ obsahu:aplikace/oktetový proudID obsahu: cv.pdf<pdf-image binary data>--2676ff6efebdb664f8f7ccb34f864e25--

Viz také

JSON-RPC Vzdálené volání procedury založené na JSON
Schéma JSON

Reference

^ „ECMAScript - 2017 Language Specification“ (PDF). Ecma-international.org. Archivovány od originál (PDF) dne 12. dubna 2015. Citováno 28. ledna 2018.
^ Roy, Fielding; Julian, Reschke. „Hypertext Transfer Protocol (HTTP / 1.1): sémantika a obsah“. Tools.ietf.org. Citováno 28. ledna 2018.
^ „Archivovaná kopie“. Archivovány od originál dne 17.07.2011. Citováno 2011-02-14.CS1 maint: archivovaná kopie jako titul (odkaz)
^ [1]^{[mrtvý odkaz ]}

[1] „ECMAScript - 2017 Language Specification“ (PDF). Ecma-international.org. Archivovány od originál (PDF) dne 12. dubna 2015. Citováno 28. ledna 2018.

[2] Roy, Fielding; Julian, Reschke. „Hypertext Transfer Protocol (HTTP / 1.1): sémantika a obsah“. Tools.ietf.org. Citováno 28. ledna 2018.

[3] „Archivovaná kopie“. Archivovány od originál dne 17.07.2011. Citováno 2011-02-14.CS1 maint: archivovaná kopie jako titul (odkaz)

[4] [1]^{[mrtvý odkaz ]}

[1]

[2]

[3]

[4]