Fundamentals of the JSON-RPC API (Release 3)

HTTP Considerations

All JSON-RPC interaction takes place over secure HTTP between the client application (e.g., web site or mobile app) and the RANDOM.ORG service. All invocations must be made via HTTP POST. In particular, HTTP GET is not supported.

The API conforms to the JSON-RPC 2.0 Transport: HTTP draft proposal.

URL

The URL for invoking the API depends on which specific service you're looking for. Please see the relevant service spec for details.

Content Types

The HTTP content type of the JSON-RPC request (sent as a HTTP request header) should be set to application/json. No other content types are accepted.

HTTP Status Codes

The HTTP status codes are set as described in the JSON-RPC 2.0 Transport: HTTP draft proposal:

Status Code	Returned When
200 OK	The request was delivered successfully to the server and a response is being returned to the client. The response may be either a JSON-RPC response object or a JSON-RPC error object.
204 No Response	The request was delivered successfully to the server, but no response was generated. This is the case if the request was a JSON-RPC notification.
307 Temporary Redirect	Not currently returned by the RANDOM.ORG API.
308 Permanent Redirect	Not currently returned by the RANDOM.ORG API.
405 Method Not Allowed	The client specified a different HTTP method than POST.
415 Unsupported Media Type	The client specified a different HTTP content type than application/json.
(others)	Transport errors or features related to HTTP (but outside the scope of JSON-RPC) may result in other HTTP Status Codes being returned.

JSON-RPC Interaction

The basic interaction between the client and the server is an exchange of request and response objects, both of which are JSON-encoded and must contain specific attributes.

Request Object Format

The JSON-RPC 2.0 Specification specifies that a request must consist of a JSON object with the following fields:

jsonrpc

A version identifier, which must be "2.0" for this version of the API.

method

The name of the method to be invoked.

params

A structured value containing the parameters that will be supplied to the method.

id

A request identifier that allows the client to match responses to request. The service will return this unchanged in its response.

Response Object Format

The service returns a JSON object with the following fields:

jsonrpc

A version identifier, which will be "2.0" for this version of the API.

result

If no error occurred, this member contains the response from the service, typically random values and other associated data. If an error occurred, this member is not included in the response.

error

If an error occurred, this member contains a service-specific error object with details about the error. If no error occurred, this member is not included in the response.

id

The identifier specified in the request.

Example Request/Response Interaction

The following shows a generic outline of a JSON-RPC 2.0 request:

{
    "jsonrpc": "2.0",
    "method": "myMethod",
    "params": {
        ...
    },
    "id": 42
}

The following shows the outline of a JSON-RPC 2.0 response:

{
    "jsonrpc": "2.0",
    "result": {
        ...
    },
    "id": 42
}

In this interaction, the client invokes the method myMethod and sets the request identifier id to 42. The service returns the same identifier in the response to allow the client to easily match the response to he request.

Error Objects

If an error occurs, RANDOM.ORG returns a JSON-RPC response in which the error property contains an object with details about the error. The error object has the following properties:

code

A numeric error code that uniquely identifies the error type.

message

A string containing a human-readable error message in English suitable for printing in a log file or as part of an error message to be displayed to a user.

data

Any values that the client needs to construct its own error message, for example in a different language than English.

The following is an example of an error object that could be returned if the client has insufficient quota to complete the request:

{
    "code": 12,
    "message": "Unable to generate random numbers; request requires 17 bits, and your remaining quota is 3",
    "data": [ 17, 3 ]
}

A full list of Error Codes and Messages is available.

API Conventions

The RANDOM.ORG API specification defines the format of methods, objects and notifications that are used between your client and our services. The following describes exactly what we mean by these three terms.

Methods

(to appear)

Objects

(to appear)

Notifications

(to appear)