Introducing the all-new TIBCO Community site!

For current users, please click "Sign In" to reset your password and access the enhanced features. If you're a first-time visitor, we extend a warm welcome—click "Sign Up" to become a part of the TIBCO Community!

If you're seeking alternative community sites, explore ibi, Jaspersoft, and Spotfire.

Jump to content
  • TIBCO Mashery® JSON RPC


    Manoj Chaurasia

    Table of Contents

    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 asynchronous requests with responses

    JSON-RPC 1.0 sample request

    This is the baseline 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 asynchronous 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.

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

     

    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 asynchronous 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 adds 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 CodeJSON-RPC CodeError MessageDescription
    400-32600Invalid requestAn HTTP Method other than POST was used or the posted message body was empty.
    400-32700Invalid json

    The request passed was not valid JSON.

    400-32600Invalid 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-32602Invalid parametersThe parameter field is missing or not an array.
    400-32600Method namespace is requiredThe method name passed does not contain a namespace designator.
    404-32601Namespace not foundThe namespace portion of the method name cannot be found.
    404-32601Method not foundThe method cannot be found in the specified namespace.
    400-32602Unexpected additional parametersYou have passed more parameters than the method expected to receive
    400-32602Missing Required ParameterYou have passed fewer parameters than the method requires
    400-32601Invalid method formatMethod name is not in a valid format
    400-32600Bad requestA malformed HTTP request was made.
    414-32600Request-URI Too LongThe uri requested is too long.

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

    HTTP Status CodeJSON-RPC CodeError MessageDescription
    500-32603Internal Server ErrorIndicates an error occurred while processing the request.  All internal server errors are logged and monitored.
    502-32603Bad GatewayIndicates an internal network connectivity issue at Mashery.
    503-32000Service UnavailableThis service is currently unavailable.  Please follow MasheryOps for real time information about outages and scheduled maintenance at Mashery.
    504-32603Gateway TimeoutIndicates an 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, and 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 that 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 the update.

    This is a boolean value that 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)

    User Feedback

    Recommended Comments

    There are no comments to display.


×
×
  • Create New...