请输入您要查询的百科知识：

　

词条 JSON-WSP
释义

  1. Specifications

      Understanding the specification notation    Building blocks    Common building blocks    Description object database   Additional building blocks    Specification    Descriptions    Request object    Specification    Response object    Specification    Fault response object    Additional building blocks    Specification    Descriptions  

  2. Real-world example

      Description    Service call 1    Request    Response    Service call 2    Request    Response  

  3. Attachments

      Attachment service description example    Attachment service request example  

  4. Server implementations

  5. Client implementations

  6. See also

  7. References

[https://en.wikipedia.org/w/index.php?oldid=757972316 This article] is on hold (will be deleted), perhaps you are searching for JSON-RPC or JSON Schema.

{{Multiple issues|{{Original research|date=July 2014}}{{Notability|date=January 2018}}{{Refimprove|date=January 2018}}}}

JSON-WSP (JavaScript Object Notation Web-Service Protocol) is a web-service protocol that uses JSON[1] for service description, requests and responses. It is inspired from JSON-RPC, but the lack of a service description specification with documentation in JSON-RPC sparked the design of JSON-WSP.

The description format has the same purpose for JSON-WSP as WSDL has for SOAP or IDL for CORBA, which is to describe the types and methods used in a given service. It also describes inter-type relations (i.e. nested types) and defines which types are expected as method arguments and which types the user can expect to receive as method return values. Finally the description opens the possibility to add documentation on service, method, parameter and return levels.

Communication between clients and a JSON-WSP server is carried out using HTTP POST[2] requests and responses, with the JSON objects as data with the content-type application/json.[3]

Specifications

JSON-WSP consists of four JSON object specifications:

SpecificationDescription
descriptionService description specification (like WSDL). This specification describes methods, method parameters, types and return types. It also supports user documentation on service, method and parameter levels.
requestSpecification for JSON requests. It contains information about which method that is to be invoked and all the arguments for the method call. Arguments in the request must obey the parameter definition of the same method described in the corresponding JSON-WSP description.
responseSpecification for JSON responses. The response object contains the result of a service method invocation. The return type must obey the defined return type of the same method in the corresponding JSON-WSP description.
faultSpecification for JSON fault responses. The fault object contains a fault code and a fault string. The fault information specifies whether the fault occurred on the client or server side. Depending on the server side service framework more detailed information can be extracted, i.e. the filename and line number where the fault occurred.

NOTE: JSON-WSP specification 1.0 is still{{When|date=July 2012}} not final. Please refer to the real-world example in this article to get an idea of how the specification is going to be structured. The current state of the actual specification is kept at launchpad.net:.[4] An RFC proposal is currently being created and hopefully accepted within a couple of months.{{When|date=July 2012}}

Understanding the specification notation

Building blocks

  • If the name of the building block being defined starts with rx-, it means that the definition is a regular expression. In these definitions square brackets have the role of defining character classes and parentheses have the role of defining capturing groups.
  • In all other cases, square brackets notate lists and parentheses notate either a decision:{{sp?|date=October 2011}}:
    ( d1 | d2 | ... )
    a repetition of 0-many:
    ( ... )
    a repetition 1-many:
    ( ... )+
    or something optional:
    ( ... )?

Common building blocks

= ".*"

= "[a-zA-Z_][a-zA-Z0-9_]*"

= [0-9]+

= (true|false)

=

= ( | | )

= (

|

    [ ( , )* ] |    { ( : , )* } )
= =

Description object database

Additional building blocks

= ( "string" | "number" | "float" | "attachment" )

= = =

= ( | | [] | [] )

= = = =

Specification

{
    "type": "jsonwsp/description",    "version": "1.0",    "servicename": ,    "url": ,    "types": { (

: { (

: )+

        } )*    },    "methods": { (

: {

            "doc_lines": [ ( , )* ],            "params": { (

: {

                    "doc_lines": [ ( , )* ],                    "def_order": ,                    "type": ,                    "optional":                 }, )*            },            "ret_info": {                "doc_lines": [ ( , )* ],                "type":             }        } )+    }

}

Descriptions

:

The service endpoint URL that accepts JSON-WSP POST request objects.

:

Service name is case sensitive. It identifies a specific service exposed on a specific server.

doc_lines:

Each doc-string contained in a doc_lines list reflects a single line of documentation that relates to the parent object of the doc_lines..

Request object

The request object contains information about which method to invoke and what arguments to invoke the method with. It also stores information about the type and version of itself.

The optional mirror value can be used to send information from the client which will then be reflected by the server and returned unchanged in the response object's reflection value. This feature allows clients to send multiple requests to a method and send request identification values that can be intercepted by the client's response handler. This is often necessary from javascript if more than one request is being processed simultaneously by the server and the response order is unknown by the client.

Specification

{
    "type": "jsonwsp/request",    "version": "1.0",    "methodname": ,    "args": { ( : , )* }(,    "mirror":  )?

}

Response object

Specification

The reflection value is an unchanged server reflection of the request object's mirror value. It is marked as optional because it is the client that controls via the request whether it is there or not.

{
    "type": "jsonwsp/response",    "version": "1.0",    "servicename": ,    "methodname": ,    "result": (,    "reflection":  )?

}

Fault response object

Additional building blocks

= ( "incompatible" | "client" | "server" )

= = =

Specification

{
    "type": "jsonwsp/fault",    "version": "1.0",    "fault": {        "code": ,        "string": ,        ("detail": [ ( , )* ] ,)?        ("filename": ,)?        ("lineno": ,)?    }(,    "reflection":  )?

}

Descriptions

:

The meanings of the possible fault-codes:

  • "incompatible": Client version of JSON-WSP is incompatible with the server version of JSON-WSP. Typically one will encounter this type of fault-code if there is a version major in difference between the client and the server.
  • "server": An error occurred on the server side after the client request has been successfully consumed.
  • "client": The clients request could not be consumed by the server due to incorrect format or missing required arguments etc.

Real-world example

Description

{
    "type": "jsonwsp/description",    "version": "1.0",    "servicename": "UserService",    "url": "http://testladon.org:80/proxy.php?path=UserService/jsonwsp",    "types": {        "Group": {            "group_id": "number",            "display_name": "string",            "name": "string",            "members": ["User"]        },        "User": {            "username": "string",            "user_id": "number",            "mobile": "string",            "age": "number",            "given_name": "string",            "surname": "string"        },        "CreateUserResponse": {            "user_id": "number",            "success": "boolean"        }    },    "methods": {        "listUsers": {            "doc_lines": ["List Users that have a username, given_name or surname that matches a given filter."],            "params": {                "name_filter": {                    "def_order": 1,                    "doc_lines": ["String used for filtering the resulting list of users."],                    "type": "string",                    "optional": false                }            },            "ret_info": {                "doc_lines": ["List of users."],                "type": ["User"]            }        },        "listGroups": {            "doc_lines": ["List Groups that have a name or display_name that matches a given filter."],            "params": {                "name_filter": {                    "def_order": 1,                    "doc_lines": ["String used for filtering the resulting list of groups."],                    "type": "string",                    "optional": false                }            },            "ret_info": {                "doc_lines": ["List of groups."],                "type": ["Group"]            }        },        "createUser": {            "doc_lines": ["Create a new user account."],            "params": {                "username": {                    "def_order": 1,                    "doc_lines": ["Unique username for the new user account."],                    "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": ["Optional mobile number."],                    "type": "string",                    "optional": true                },                "age": {                    "def_order": 5,                    "doc_lines": ["Optional age of the person behind the account."],                    "type": "number",                    "optional": true                }            },            "ret_info": {                "doc_lines": [],                "type": "CreateUserResponse"            }        }    }

}

Service call 1

Request

{
    "type": "jsonwsp/request",    "version": "1.0",    "methodname": "createUser",    "args": {        "username": "bettyw",        "given_name": "Betty",        "surname": "Wilson",        "mobile": "555-3423444"    },    "mirror": {        "id": 2    }

}

Response

{
    "type": "jsonwsp/response",    "version": "1.0",    "servicename": "UserService",    "methodname": "createUser",    "result": {        "user_id": 324,        "success": true    },    "reflection": {        "id": 2    }

}

Service call 2

Request

{
    "type": "jsonwsp/request",    "version": "1.0",    "methodname": "listUsers",    "args": {        "name_filter": "jack"    }

}

Response

{
    "type": "jsonwsp/response",    "version": "1.0",    "servicename": "UserService",    "methodname": "listUsers",    "result": [{        "username": "jackp",        "user_id": 153,        "mobile": "555-377843",        "age": 34,        "given_name": "Jack",        "surname": "Petersen"    }, {        "username": "bradj",        "user_id": 321,        "mobile": "555-437546",        "age": 27,        "given_name": "Brad",        "surname": "Jackson"    }]

}

Attachments

The attachment type is new in JSON-WSP. It can be used anywhere in the description as a primitive type. In requests and responses that involve attachments, the message format must be multipart/related where the attachments are transported as mimeparts of media type: application/octet-stream with no Content-Transfer-Encoding (only raw binary). Mimeparts must have a unique CONTENT-ID in their entity headers. Attachment values in the JSON-WSP request/response objects must match the regular expression "^cid:(.+)$" where the capture group maps to one of the mimepart's CONTENT-ID.

Attachment service description example

The following example shows what a simple JSON-WSP description with attachments could look like:

{
    "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                }            }        }    }

}

Attachment service request example

A request to the method "upload" described above could look like this:

Content-Type: multipart/related; boundary="2676ff6efebdb664f8f7ccb34f864e25"

--2676ff6efebdb664f8f7ccb34f864e25

Content-Type: application/json, charset=UTF-8

Content-ID: body

{
    "type": "jsonwsp/request",    "version": "1.0",    "methodname": "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

--2676ff6efebdb664f8f7ccb34f864e25

Content-Type: application/octet-stream

Content-ID: cv.pdf

--2676ff6efebdb664f8f7ccb34f864e25--

Server implementations

  • ladon at PyPI Ladon is a Python-based framework that exposes json-wsp and other protocols
  • ladon at ladonize.org ladonize.org is the official homepage for ladon. It contains running demos.
  • [https://bitbucket.org/pfacka/jsonwsp pfacka/jsonwsp] A Python JSON-WSP server implentation]

Client implementations

  • [https://github.com/mikrov/jsonwsp-php PHP Client]
  • [https://github.com/mikrov/jsonwsp-cs C# Client]
  • [https://pypi.python.org/pypi/ladon ladon at PyPI] contains a Python client (from ladon.clients.jsonwsp import JSONWSPClient)
  • JavaScript client
  • [https://launchpad.net/jsonwsp-cpp C++ Client] (Not entirely complete)
  • [https://bitbucket.org/pfacka/jsonwsp pfacka/jsonwsp] Python client
  • [https://github.com/bobuk/jsonwsp-client bobuk/jsonwsp-client] Python client

See also

  • JSON-RPC JSON-based remote procedure call
  • JSON Schema
  • [https://github.com/brutusin/jsonsrv org.brutusin:jsonsrv library], a web-service protocol that uses JSON and JSON-schema
  • [https://jsonformatter.org/ JSON Formatter] Online

References

1. ^{{cite web|url=http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-262.pdf|format=PDF|title=ECMAScript® 2017 Language Specification|website=Ecma-international.org|accessdate=28 January 2018}}
2. ^{{cite web|url=http://tools.ietf.org/html/rfc7231#section-4.3.3|title=Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content|first1=Fielding,|last1=Roy|first2=Reschke,|last2=Julian|website=Tools.ietf.org|accessdate=28 January 2018}}
3. ^  {{dead link|date=January 2018}}
4. ^  {{dead link|date=May 2013}}

3 : Web services|Web service specifications|Remote procedure call
随便看

　

开放百科全书收录14589846条英语、德语、日语等多语种百科知识，基本涵盖了大多数领域的百科知识，是一部内容自由、开放的电子版国际百科全书。

　

Copyright © 2023 OENC.NET All Rights Reserved
京ICP备2021023879号 更新时间：2024/11/11 19:04:14