JSON RPC

About JSON-RPC

The Mashery API is JSON-RPC based.  Requests and responses in JSON-RPC are valid JSON.

The API responds to calls in 1.0, 1.1 and 2.0 formats. If a request conforms to a particular version, the result will conform to the version used in the request.

The JSON-RPC 1.0 specification is documented at http://json-rpc.org.

The JSON-RPC 1.1 specification is documented at http://json-rpc.org/wd/JSON-RPC-1-1-WD-20060807.html

The JSON-RPC 2.0 specification is documented at http://www.jsonrpc.org/specification

Request

A simple JSON-RPC request consists of a JSON object with three parameters.  Different versions of the JSON-RPC protocol may also use a parameter to indicate which version of the protocol is being employed.

method

The name of the method to call

params

A positional list of parameters to pass

id

The id number is used to match asyncronous requests with responses

JSON-RPC 1.0 sample request

This is the base line version of the protocol used if no other version is specified.

{
    "method": "test.hello",
    "params": [],
    "id": 1
}

JSON-RPC 1.1 sample request

The version parameter indicates the version of the protocol.

{
    "version": "1.1",
    "method": "test.hello",
    "params": [],
    "id": 1
}

JSON-RPC 2.0 sample request

The jsonrpc parameter indicates the version of the protocol.

{
    "jsonrpc": "2.0",
    "method": "test.hello",
    "params": [],
    "id": 1
}

Response

A successful response is a JSON object with two core fields.

result

The result of the method call.

id

The id number is used to match asyncronous requests with responses

JSON-RPC 1.0 sample response

A successful JSON-RPC 1.0 response will always return an error field with a value of null.

{
    "result": "Hello!",
    "error": null,
    "id": 1
}

JSON-RPC 1.1 sample response

A version field indicates the version of the response.

{
    "id": 1,
    "version": "1.1",
    "result": "Hello!"
}

JSON-RPC 2.0 sample response

A jsonrpc field indicates the version of the response.

{
    "jsonrpc": "2.0",
    "result": "Hello!",
    "id": 1
}

Error Response

An error response is a JSON object with two core fields.

error

Returns an error object.  This object will contain a code field and a message field describing the error.

id

The id number is used to match asyncronous requests with responses

Note that for some error messages, the format returned will default to json-rpc 1.0 format instead of the version of the protocol matching the request.  Additionally, for some error conditions, it is not possible to match the id parameter in the error response with the id in the error request.  In this case, an id of 0 will be used.  These conditions occur only for protocol errors listed on this page and for authentication errors listed under Authentication.

JSON-RPC 1.0 sample error response

Version 1.0 continues to include the result field even in an error response.

{
    "result": null,
    "error": {"code":-32700, "message":"Permission Denied"},
    "id": 1
}

JSON-RPC 1.1 sample error response

Version 1.1 drops the result field and ads a name field to the error object.

{
    "id": 1,
    "version": "1.1",
    "error": {"code":-32700, "message":"Permission Denied", "name":"JSONRPCError"}
}

JSON-RPC 2.0 sample error response

Version 2.0 drops the result field and the name field in the error object.

{
    "jsonrpc": "2.0",
    "error": {"code":-32700, "message":"Permission Denied"},
    "id": 1
}

Error Messages

The following errors indicate an invalid usage of the json-rpc protocol with the Mashery API.

The following are general errors which can occur while using the mashery API.

Describing Services with JSON Schema

The Mashery API uses JSON Schema to describe API methods, parameters and return results.  A JSON Schema description of each object supported by the api can be obtained from the object.describe call.

JSON Schema is described here:

http://www.json.com/json-schema-proposal/

Mashery JSON Schema Extensions

We've added some mashery specific extensions to JSON Schema.

sortable

sortable indicates when an object field may be used in an object query.

This is a boolean value which defaults to FALSE if absent.

createonly

create only indicates that a field can only be set when an object is created and cannot be changed during update.

This is a boolean value which defaults to FALSE if absent.

queryable

queryable indicates when an object field may be used in an object query.

This is a boolean value which defaults to TRUE if absent.

Unsupported JSON-RPC Features

Some features of JSON-RPC are not currently supported by the Mashery API.

• Named parameters (1.1)
• HTTP GET Encoding (1.1)
• Introspection methods or system service (1.1)
• Notifications
• Batched Calls
• Optional id parameter(1.1)