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.

HTTP Status Code JSON-RPC Code Error Message Description
400 -32600 Invalid request An HTTP Method other than POST was used or the posted message body was empty.
400 -32700
Invalid json

The request passed was not valid JSON.

400 -32600 Invalid json-rpc request

The json passed does not conform to JSON-RPC. Examples might include a missing or non-integer id field or a missing or non-string method field.

400 -32602 Invalid parameters
The parameter field is missing or not an array.
400 -32600 Method namespace is required
The method name passed does not contain a namespace designator.
404 -32601 Namespace not found The namespace portion of the method name cannot be found.
404 -32601 Method not found The method cannot be found in the specified namespace.
400 -32602 Unexpected additional parameters You have passed more parameters than the method expected to receive
400 -32602 Missing Required Parameter You have passed fewer parameters than the method requires
400 -32601 Invalid method format Method name is not in a valid format
400 -32600 Bad request A malformed HTTP request was made.
414 -32600 Request-URI Too Long The uri requested is too long.

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

HTTP Status Code JSON-RPC Code Error Message Description
500 -32603 Internal Server Error Indicates an error occured while processing the request.  All internal server errors are logged and monitored.
502 -32603 Bad Gateway Indicates a internal network connectivity issue at Mashery.
503 -32000 Service Unavailable This service is currently unavailable.  Please follow MasheryOps for real time information about outages and scheduled maintainance at Mashery.
504 -32603 Gateway Timeout Indicates a internal network connectivity issue at Mashery or a request that has taken too long to complete.

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)

Docs Navigation