True Random Number Service

Note: There is a newer version of this API available.

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:

If a JSON-RPC request is successful, a HTTP response code 200 is returned.
If a JSON-RPC request fails due to a client error (e.g., a malformed request or an attempt to invoke a nonexistent method), a HTTP response code 400 (Bad Request) or 404 (Method Not Found) is returned.
If a JSON-RPC request fails due to a server error, a HTTP response code 500 (Internal Server Error) is returned.

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.