True Random Number Service

JSON-RPC API – Release 1 – Introduction

JSON-RPC is a simple remote procedure call protocol encoded in JSON. Implementations of JSON-RPC exist in many languages. In JavaScript, JSON-RPC is so simple to use that you most likely won't need a client library. For some other languages, source code is available.

Versions Supported

The API supports JSON-RPC 2.0, except that notifications and batch requests are not supported. Other than that, the interaction is intended to be fully consistent with the JSON-RPC 2.0 Specification and RFC4627 on JavaScript Object Notation (JSON) in all regards. The Wikipedia entry for JSON-RPC is also a helpful resource.

HTTP Considerations

Transport

All interaction takes place via JSON-RPC 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.

URL

The URL for invoking the API is https://api.random.org/json-rpc/1/invoke

Content Types

The HTTP content type of the JSON-RPC request (sent as a HTTP request header) should be set to application/json-rpc. The following are also accepted: application/json and application/jsonrequest.

Response Codes

The HTTP response codes are set as follows:

JSON-RPC Interaction

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 the 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.

© 1998-2017 RANDOM.ORG
Terms and Conditions
About Us