Войти
JSON-WSP (протокол веб-службы нотации объектов JavaScript) - это протокол веб-службы, использующий JSON для описания услуги, запросов и ответов. Он основан на JSON-RPC, но отсутствие спецификации описания службы с документацией в JSON-RPC спровоцировало разработку JSON-WSP.
Формат описания имеет ту же цель для JSON-WSP, что и WSDL для SOAP или IDL для CORBA, который должен описывать типы и методы, используемые в данной службе. Он также описывает отношения между типами (то есть вложенные типы) и определяет, какие типы ожидаются в качестве аргументов метода и какие типы пользователь может ожидать в качестве возвращаемых значений метода. Наконец, описание открывает возможность добавления документации по уровням обслуживания, метода, параметра и возврата.
Связь между клиентами и сервером JSON-WSP осуществляется с использованием запросов и ответов HTTP POST, с объектами JSON в качестве данных с приложением типа содержимого / json.
JSON-WSP состоит из четырех спецификаций объекта JSON:
| Спецификация | Описание |
|---|---|
| description | Спецификация описания службы (например, WSDL ). В этой спецификации описаны методы, параметры методов, типы и возвращаемые типы. Он также поддерживает пользовательскую документацию на уровне услуг, методов и параметров. |
| запрос | Спецификация для запросов JSON. Он содержит информацию о том, какой метод должен быть вызван, и все аргументы для вызова метода. Аргументы в запросе должны подчиняться определению параметра того же метода, которое описано в соответствующем описании JSON-WSP. |
| ответ | Спецификация для ответов JSON. Объект ответа содержит результат вызова метода службы. Тип возврата должен соответствовать определенному типу возврата того же метода в соответствующем описании JSON-WSP. |
| ошибка | Спецификация ответов на ошибку JSON. Объект ошибки содержит код ошибки и строку ошибки. Информация об ошибке указывает, произошла ли ошибка на стороне клиента или на стороне сервера. В зависимости от инфраструктуры службы на стороне сервера может быть извлечена более подробная информация, например имя файла и номер строки, в которой произошла ошибка. |
ПРИМЕЧАНИЕ. Спецификация JSON-WSP 1.0 еще не окончательная. Пожалуйста, обратитесь к реальному примеру в этой статье, чтобы получить представление о том, как будет структурирована спецификация. Текущее состояние спецификации хранится на launchpad.net :. Предложение RFC в настоящее время создается и, надеюсь, будет принято в течение пары месяцев.
(d1 | d2 |...)повторение 0-многие:
(...) *повторение 1-много:
(...) +или что-то необязательное:
(...)?
= ". *" = "[a-zA-Z _] [a-zA-Z0-9_ ] * " = [0-9] + = (true | false) = = ( | | ) = ( | [( ,) *] | {( : ,) *}) = =
= ("строка" | "число" | "float" | "attachment") = = = = ( | | [ ] | [ ]) = = = =
{"тип": "jsonwsp / description", "версия": "1.0", "servicename" : , «url»: , «типы»: {(: {(: ) +}) *}, «методы»: {(: { "doc_lines": [(,) *], "params": {(: {"doc_lines": [(,) *], "def_order": , "typ e ": ," optional ": },) *}," ret_info ": {" doc_lines ": [(,) *]," type ": }}) + }} doc_lines: Каждая строка документа, содержащаяся в списке doc_lines, отражает одну строку документации, которая относится к родительскому объекту doc_lines..
Запрос Объект содержит информацию о том, какой метод вызывать и с какими аргументами вызывать метод. Он также хранит информацию о своем типе и версии.
Необязательное значение mirror может использоваться для отправки информации от клиента, которая затем будет отражена сервером и возвращена без изменений в значении Reflection объекта ответа. Эта функция позволяет клиентам отправлять несколько запросов к методу и отправлять значения идентификации запроса, которые могут быть перехвачены обработчиком ответа клиента. Это часто необходимо из javascript, если сервером одновременно обрабатывается более одного запроса, а порядок ответа неизвестен клиенту.
{"тип": "jsonwsp / request", "версия": "1.0", "имя метода": , "args": {(: ,) *} (, "зеркало": )? } Значение Reflection - это неизменное серверное отражение значения mirror объекта запроса. Он помечен как необязательный, потому что именно клиент контролирует с помощью запроса, есть ли он там или нет.
{"type": "jsonwsp / response", "version": "1.0", "servicename": , "methodname": , "result": (, "отражение" : )? } = ("несовместимый" | "клиент" | "сервер") = = =
{"тип": "jsonwsp / fault", «версия»: «1.0», «ошибка»: {«код»: , «строка»: , («деталь»: [(,) *],)? ("имя файла": ,)? ("белье": ,)? } (, "отражение": )? } {" type ":" jsonwsp / description "," version ":" 1.0 "," servicename ":" UserService "," url ":" http://testladon.org:80/proxy.php?path=UserService/jsonwsp ", "типы": {"Группа": {"идентификатор_группы": "число", "отображаемое_имя": "строка", "имя": "строка", "члены": ["Пользователь"]}, "Пользователь": {"username": "string", "user_id": "number", "mobile": "string", "age": "number", "given_name": "string", "surname": "string"}, "CreateUserResponse": {"user_id": "number", "success": "boolean"}}, "methods": {"listUsers": {"doc_lines": ["Список пользователей, у которых есть имя пользователя, given_name или фамилия, которые матч как заданный фильтр. "]," params ": {" name_filter ": {" def_order ": 1," doc_lines ": [" Строка, используемая для фильтрации результирующего списка пользователей. "]," type ":" string ", "optional": false}}, "ret_info": {"doc_lines": ["Список пользователей."], "type": ["User"]}}, "listGroups": {"doc_lines": ["Список Группы, у которых есть имя или отображаемое имя, которое соответствует заданному фильтру. "]," Params ": {" name_filter ": {" def_order ": 1," doc_lines ": [" Строка, используемая для фильтрации результирующего списка групп. "], "type": "string", "optional": false}}, "ret_info": {"doc_lines": ["Список групп."], "type": ["Group"]}}, "createUser" : {"doc_lines": ["Создать новую учетную запись пользователя."], "params": {"username": {"def_order": 1, "doc_lines": ["Уникальное имя пользователя для новой учетной записи пользователя."], "type": "string", "optional": false}, "given_name": {"def_order": 2, "doc_lines": ["First name."], "type": "string", "optional": false}, "surname": {"def_order": 3, "doc_lines": ["Last name."], "type": "string", "optional": false}, "mobile": { «def_order»: 4, «doc_lines»: [«Необязательный номер мобильного телефона.»], «type»: «строка», «optional»: true}, «age»: {«def_order»: 5, «doc_lines»: [ "Необязательный возраст лица, стоящего за аккаунтом."], "Type": "number", "optional": true}}, "ret_info": {"doc_lines":, "type": "CreateUserResponse"}}}}{"тип": "jsonwsp / request", "версия": "1.0", "имя метода": "createUser", "args": {"имя пользователя ":" bettyw "," given_name ":" Betty "," surname ":" Wilson "," mobile ":" 555-3423444 "}," mirror ": {" id ": 2}}{"type": "jsonwsp / response", "version": "1.0", "servicename": "UserService", "methodname": "createUser", "result": {"user_id": 324, "success ": true}," reflection ": {" id ": 2}}{" type ":" jsonwsp / request "," version ":" 1.0 "," methodname ":" listUsers "," args ": {" name_filter ":" jack "}}{" type ":" jsonwsp / response "," version ":" 1.0 ", "servicename": "UserService", "methodname": " listUsers "," result ": [{" username ":" jackp "," user_id ": 153," mobile ":" 555-377843 "," age ": 34," given_name ":" Jack "," фамилия " : "Petersen"}, {"username": "bradj", "user_id": 321, "mobile": "555-437546", "age": 27, "given_name": "Brad", "surname": " Джексон "}]}Тип вложения является новым в JSON-WSP. Его можно использовать в любом месте описания как примитивный тип. В запросах и ответах, содержащих вложения, формат сообщения должен быть multipart / related, где вложения транспортируются как mimeparts типа мультимедиа: application / octet-stream без Content-Transfer- Кодировка (только необработанный двоичный код). Mimeparts должны иметь уникальный CONTENT-ID в заголовках объектов. Значения вложений в объектах запроса / ответа JSON-WSP должны соответствовать регулярному выражению «^ cid: (. +) $», Где группа захвата сопоставляется с одним из идентификаторов CONTENT-ID mimepart.
В следующем примере показано, как может выглядеть простое описание JSON-WSP с вложениями:
{"type": "jsonwsp / description", "version" : "1.0", "url": "http://mysite.com/TransferService/jsonwsp", "servicename": "TransferService", "types": {"File": {"data": "attachment", " name ":" string "}}," methods ": {" upload ": {" ret_info ": {" doc_lines ":," type ":" number "}," doc_lines ":," params ": {" incoming ": {" def_order ": 1," doc_lines ":," type ": [" File "]," optional ": false}}}}}Запрос на описанный выше метод загрузки может выглядеть так:
Content-Type: multipart / related; border = "2676ff6efebdb664f8f7ccb34f864e25" --2676ff6efebdb664f8f7ccb34f864e25 Content-Type: application / json, charset = UTF-8 Content-ID: body {"type": "jsonwsp / request", "version": "1.0", "version": "1.0", "version": "1.0", upload "," args ": {" incoming ": [{" data ":" cid: img2354.png "," name ":" face.png "}, {" data ":" cid: cv.pdf ", "name": "cv.pdf"}]}} --2676ff6efebdb664f8f7ccb34f864e25 Content-Type: application / octet-stream Content-ID: img2354.png --2676ff6efebdb664f8f7ccb34f864e25c Content-Type: application-Content-Type : cv.pdf --2676ff6efebdb664f8f7ccb34f864e25-- 