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.
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.
application/json
.application/json
. In particular, application/json-rpc
and application/jsonrequest
are no longer allowed.generateIntegerSequences
generateSignedIntegerSequences
getResult
userData
was added to the following methods:
generateSignedIntegers
generateSignedDecimalFractions
generateSignedGaussians
generateSignedStrings
generateSignedUUIDs
generateSignedBlobs
license
and userData
were added to random
objects returned by the following methods:
generateSignedIntegers
generateSignedDecimalFractions
generateSignedGaussians
generateSignedStrings
generateSignedUUIDs
generateSignedBlobs
generateDecimalFractions
would not return enough signficant digits when more than 14 were requested.
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.
The URL for invoking the API depends on which specific service you're looking for. Please see the relevant service spec for details.
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.
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. |
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.
The JSON-RPC 2.0 Specification specifies that a request must consist of a JSON object with the following fields:
jsonrpc
"2.0"
for this version of the API.method
params
id
The service returns a JSON object with the following fields:
jsonrpc
"2.0"
for this version of the API.result
error
id
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.
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
message
data
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.
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.
(to appear)
(to appear)
(to appear)