SOAPjr

From HandWiki

SOAPjr is a protocol specification for exchanging structured information in the implementation of web services in computer networks. It is a hybrid of SOAP and JSON-RPC (abbreviated as "jr" in this case).

Introduction

SOAPjr is designed to create clean, fast, Ajax-style APIs and is analogous to the introduction of out of band signalling in the telephony world.

Traditional SOAP[1] is no longer the Simple Object Access Protocol it was initially designed to be. It can be bloated and overly verbose, making it bandwidth-hungry and slow.[2] It is also based on XML, making it expensive to parse and manipulate [3] - especially on mobile or embedded clients.[4] However, its core envelope/head/body design pattern is useful for Ajax style APIs.[5]

SOAPjr uses a similar Envelope/Head/Body model, using lightweight and easier to manipulate JSON.[6]

In contrast to SOAP, JSON-RPC[7] is overly simplistic and basically tunnels HTTP[8] GET-style key/value pairs within a query string using JSON. However, within JSON-RPC there is no head/body separation, leaving metadata to pollute the main data space.

SOAPjr combines the best of these two concepts and is designed to create modern Ajax APIs that can easily be used by mobile devices, embedded systems or desktop browsers.

See SOAPjr Specs for a more detailed description.

SOAPjr is an Open Source project with software released under the GPL and content under Creative Commons.

JSON-Schema definitions

The following SOAPjr entities are defined as JSON-Schemas.

The latest versions can also be downloaded in a single file.

Common data models

SOAPjr.org also aims to contribute to the creation of a common set of DMDs (Data Model Definitions)[9] that may align with the JSON-schema proposal[10] and Service Mapping Description Proposal[11] so applications within specific domains can easily share data. The primary extension that SOAPjr may provide here is the use of consistent or standardised error codes.

Other resources that may inform this development are common data models utilised within microformats[12][13] and RDF[14]

Examples

This is a basic request to view the jCard details for a single user (based on their username). This message would be passed in a request within the "json" parameter e.g.

?json={"HEAD":{"service_type":"contacts","action_type":"view",
"sid":"80e5b8a8b9cbf3a79fe8d624628a0fe5"},"BODY":{"username":"jbloggs"}}
{
    "HEAD" : {
        "service_type" : "contacts",
        "action_type" : "view",
        "sid" : "80e5b8a8b9cbf3a79fe8d624628a0fe5"
    },
    "BODY" : {
        "username" : "jbloggs"
    }
}

This is a simple SOAPjr response with a HEAD.result that represents a success. The BODY contains a single jCard record. In a list "list" or "search" context this would contain an array of 0 or more jCard records.

{
    "HEAD" : {
        "result" : "1"
    },
    "BODY" : {
        "email" : [
            {
                "type" : ["internet","pref"],
                "value" : "spam@SOAPjr.org"
            }
        ],
        "fn" : "Joe Bloggs",
        "kind" : "individual",
        "n" : {
            "family-name" : ["Bloggs"],
            "given-name" : ["Joe"],
            "value" : "Bloggs;Joe"
        },
        "org" : [
            {
                "organization-name" : "SOAPjr.org"
            }
        ]
    }
}

See also

References

External links