SOAPjr

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 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. It is also based on XML, making it expensive to parse and manipulate - especially on mobile or embedded clients. However, its core envelope/head/body design pattern is useful for Ajax style APIs.

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

In contrast to SOAP, JSON-RPC is overly simplistic and basically tunnels HTTP 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.

• SOAPjr_basic_object
• SOAPjr_error_record
• SOAPjr_errors_object
• SOAPjr_request
• SOAPjr_response

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) that may align with the JSON-schema proposal and Service Mapping Description Proposal 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 and RDF

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

• Remote procedure call
• SOAP
• JSON-RPC
• JSON

External links

• SOAPjr Main Page
• SOAPjr jQuery Plugin
• SOAPjr Perl modules on CPAN
• pSOAPjr php project
• SOAPjr demonstration
• Augmented Reality website built using SOAPjr