Fundamentals of the JSON-RPC API (Release 2)

  1. RANDOM.ORG
  2. API
  3. JSON-RPC
  4. Release 2
  5. Fundamentals

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 RANDOM.ORG API supports JSON-RPC 2.0, except 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.

Changes from Release 1

  • Release 2 conforms to the JSON-RPC 2.0 Transport: HTTP draft proposal, resulting in the following:
    • HTTP status code 204 is now returned if the JSON-RPC response is empty.
    • HTTP status code 405 is now returned if the HTTP request method is not POST.
    • HTTP status code 415 is now returned if the HTTP content type of the request is not application/json.
    • The HTTP content type of the request must now be application/json. In particular, application/json-rpc and application/jsonrequest are no longer allowed.
  • The following new methods were added:
    • generateIntegerSequences
    • generateSignedIntegerSequences
    • getResult
  • A new optional parameter userData was added to the following methods:
    • generateSignedIntegers
    • generateSignedDecimalFractions
    • generateSignedGaussians
    • generateSignedStrings
    • generateSignedUUIDs
    • generateSignedBlobs
  • Two additional properties license and userData were added to random objects returned by the following methods:
    • generateSignedIntegers
    • generateSignedDecimalFractions
    • generateSignedGaussians
    • generateSignedStrings
    • generateSignedUUIDs
    • generateSignedBlobs
  • A bug was fixed in which generateDecimalFractions would not return enough signficant digits when more than 14 were requested.

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

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)

Terms and Conditions | Privacy | About Us | Contact Us
© 1998-2021 RANDOM.ORG