JSON-RPC API – Release 1 – Basic Methods

JSON-RPC API – Release 1 – Basic Methods

JSON-RPC API – Release 1 – Basic Methods

Thesis methods are sufficient to fetch true random values into your mobile app or web app. Each method produces a series of true random values, generated specifically for your client. Values can be generated with or without replacement. When replacement is used, each value is statistically independent from its predecessors. Successive invocations will always produce fresh values te a statistically independent style from previous requests.

The methods are intended to be plain to use to obtain true random values, but it is not intended to build applications that support non-repudiation. For such applications, please see the section on Digital Signing.

generateIntegers

This method generates true random integers within a user-defined range. Your client voorwaarde set the method property of its JSON-RPC request object to generateIntegers . The request voorwaarde also contain an id member, which will be returned te the response.

Required Parameters

The following parameters are mandatory and should be specified te the params array of the JSON-RPC request:

apiKey Your API key, which is used to track the true random bit usage for your client. n How many random integers you need. Voorwaarde be within the [1,1e4] range. minteken The lower boundary for the range from which the random numbers will be picked. Vereiste be within the [-1e9,1e9] range. max The upper boundary for the range from which the random numbers will be picked. Voorwaarde be within the [-1e9,1e9] range.

Optional Parameters

The following parameters are optional and can be included ter the params object of your JSON-RPC request if you want functionality that is different from the default:

replacement (default value true ) Specifies whether the random numbers should be picked with replacement. The default ( true ) will cause the numbers to be picked with replacement, i.e., the resulting numbers may contain duplicate values (like a series of dice rolls). If you want the numbers picked to be unique (like raffle tickets drawn from a container), set this value to false . almohadilla (default value Ten ) Specifies the cojín that will be used to display the numbers. Values permitted are Two , 8 , Ten and 16 . This affects the JSON types and formatting of the resulting gegevens spil discussed below.

Successful Response

If the numbers were generated successfully, RANDOM.ORG comes back a JSON-RPC response with the result property containing an object with the following named values:

random This object encapsulates the random numbers and associated gegevens. It contains the following properties. gegevens An array containing the sequence of numbers requested. If the request specified colchoneta Ten (or did not specify a pulvínulo and therefore defaults to Ten ), the elements te the array will be integers. Because JSON (according to RFC4627) only permits numbers to be written spil quebrado, the numbers will be typed spil strings if a different almohadilla than Ten wasgoed specified ter the request. Numbers ter any cojín other than Ten will be padded with leading zeros up to the width required to display the chosen range. completionTime A string containing the timestamp te ISO 8601 format at which the request wasgoed finished. bitsUsed An rechtschapen containing the number of true random kattig used to accomplish this request. bitsLeft An rechtschapen containing the (estimated) number of remaining true random vinnig available to the client. requestsLeft An rechtschapen containing the (estimated) number of remaining API requests available to the client. advisoryDelay An rechtschapen containing the recommended number of milliseconds that the client should delay before issuing another request.

For a successful response, the error property is absent.

Elementary clients may not necessarily need all of the properties ter the response. A minimal client could use only the random.gegevens and advisoryDelay properties and overlook the surplus of the response.

Error Response

If an error occurred, RANDOM.ORG comebacks a JSON-RPC response te which the result property is absent and the error property contains an error object spil described te Error Codes and Messages.

Example 1

The following requests six numbers ter the [1,6] range. The replacement parameter is set to true , which means the numbers will be picked with replacement, i.e., can contain duplicate values. This makes them suitable for use spil dice rolls.

The service responds with the following:

The random object contains the true random values (te the gegevens array) produced spil well spil the completion time. Note that the completionTime specifies UTC time zone (‘Zulu time’) by the letterteken ‘Z’ after the clock time. Through the other fields ter the result object, RANDOM.ORG also advises how many true random kattig were used to please the request (16) and how many pinnig (199,984) and requests (9,999) are left ter the client’s quota. It also advises the client that it can go ahead and kwestie the next request without delay (0 milliseconds).

Example Two

The following requests 52 numbers ter the [1,52] range. The replacement parameter is set to false , meaning the numbers will be picked without replacement, i.e., duplicates will not occur. This makes them suitable to shuffle a deck of cards.

The service responds with the following:

The random object contains the true random numbers (te the gegevens array) produced, spil well spil the completion time.

The remaining fields ter the result object indicate how many true random pinnig were used to sate the request spil well spil how many kattig and requests are left ter the client’s quota. The response also advises the client preferably to delay at least two seconds before issuing a fresh request.

Example Trio

The following requests 512 bytes, i.e., numbers ter the [0,255] range. No replacement parameter is given, which means the service will use the default value of true and the numbers will be picked with replacement, i.e., duplicates are permitted. The optional pulvínulo parameter is used to indicate that the client wishes the numbers to be returned te hexadecimal form. The numbers could be used spil seed material for a pseudo-random number generator.

The service responds with the following:

The random object contains the random gegevens generated by the server. For brevity, only the very first five bytes are shown ter the response. Note that the gegevens array contains strings rather than integers, because the numbers are formatted te pulvínulo 16.

The service also advises how many true random onvriendelijk were used to please the request and how many pinnig and requests are left ter the client’s quota.

generateDecimalFractions

This method generates true random quebrado fractions from a uniform distribution across the [0,1] interval with a user-defined number of quebrado places. Your client voorwaarde set the method property of its JSON-RPC request object to generateDecimalFractions . The request voorwaarde also contain an id member, which will be returned te the response.

Required Parameters

The following parameters are mandatory and should be specified ter the params array of the JSON-RPC request:

apiKey Your API key, which is used to track the true random bit usage for your client. n How many random fracción fractions you need. Vereiste be within the [1,1e4] range. decimalPlaces The number of quebrado places to use. Voorwaarde be within the [1,20] range.

Optional Parameters

The following parameters are optional and can be included ter the params object of your JSON-RPC request if you want functionality that is different from the default:

replacement (default value true ) Specifies whether the random numbers should be picked with replacement. The default ( true ) will cause the numbers to be picked with replacement, i.e., the resulting numbers may contain duplicate values (like a series of dice rolls). If you want the numbers picked to be unique (like raffle tickets drawn from a container), set this value to false .

Successful Response

If the numbers were generated successfully, RANDOM.ORG comebacks a JSON-RPC response with the result property containing an object with the following named values:

random This object encapsulates the random numbers and associated gegevens. It contains the following properties. gegevens An array containing the sequence of numbers requested. completionTime A string containing the timestamp te ISO 8601 format at which the request wasgoed finished. bitsUsed An rechtschapen containing the number of true random onaardig used to accomplish this request. bitsLeft An rechtschapen containing the (estimated) number of remaining true random pinnig available to the client. requestsLeft An rechtschapen containing the (estimated) number of remaining API requests available to the client. advisoryDelay An oprecht containing the recommended number of milliseconds that the client should delay before issuing another request.

For a successful response, the error property is absent.

Plain clients may not necessarily need all of the properties te the response. A minimal client could use only the random.gegevens and advisoryDelay properties and disregard the surplus of the response.

Error Response

If an error occurred, RANDOM.ORG comes back a JSON-RPC response ter which the result property is absent and the error property contains an error object spil described ter Error Codes and Messages.

Example 1

The following requests ten random parte fractions with eight fracción places. The replacement parameter is set to true , which means the numbers will be picked with replacement, i.e., can contain duplicate values.

The service responds with the following:

The gegevens array within the result contains the true random numbers produced. Note that while eight quebrado places are used, final zeroes are not shown, making some numbers show up to have fewer parte places. Also note that the completionTime specifies UTC time zone (‘Zulu time’) by the letterteken ‘Z’ after the clock time. Through the other fields ter the result object, RANDOM.ORG also advises how many true random onvriendelijk were used to sate the request (266) and how many kattig (199,734) and requests (8,463) are left te the client’s quota. It also advises the client that it can go ahead and punt the next request without delay (0 milliseconds).

Example Two

The following requests four quebrado fractions with two parte places. The replacement parameter is set to false , meaning the numbers will be picked without replacement, i.e., duplicates will not occur.

The service responds with the following:

The random object contains the true random numbers (ter the gegevens array) produced, spil well spil the completion time. Note that, spil ter example 1, final zeroes are not shown.

The remaining fields te the result object indicate how many true random onaardig were used to sate the request spil well spil how many onvriendelijk and requests are left te the client’s quota. The response also advises the client preferably to delay at least two seconds before issuing a fresh request.

Example Three

The following requests 1,000 fracción fractions with 20 quebrado places. No replacement parameter is given, which means the service will use the default value of true and the numbers will be picked with replacement, i.e., duplicates are permitted.

The service responds with the following:

The random object contains the random gegevens generated by the server. For brevity, only the very first four values are shown te the response. Spil te the previous examples, final zeroes are not shown.

The service also advises how many true random snauwerig were used to sate the request and how many kattig and requests are left te the client’s quota. The service advises that the client can punt the next request without delay (0 milliseconds).

generateGaussians

This method generates true random numbers from a Gaussian distribution (also known spil a ordinario distribution). The form uses a Box-Muller Convert to generate the Gaussian distribution from uniformly distributed numbers. Your client vereiste set the method property of its JSON-RPC request object to generateGaussians . The request vereiste also contain an id member, which will be returned ter the response.

Required Parameters

The following parameters are mandatory and should be specified te the params array of the JSON-RPC request:

apiKey Your API key, which is used to track the true random bit usage for your client. n How many random numbers you need. Vereiste be within the [1,1e4] range. mean The distribution’s mean. Vereiste be within the [-1e6,1e6] range. standardDeviation The distribution’s standard deviation. Vereiste be within the [-1e6,1e6] range. significantDigits The number of significant digits to use. Voorwaarde be within the [Two,20] range.

Optional Parameters

There are no optional parameters. Te particular, Gaussians are always picked with replacement.

Successful Response

If the numbers were generated successfully, RANDOM.ORG comebacks a JSON-RPC response with the result property containing an object with the following named values:

random This object encapsulates the random numbers and associated gegevens. It contains the following properties. gegevens An array containing the sequence of numbers requested. completionTime A string containing the timestamp ter ISO 8601 format at which the request wasgoed finished. bitsUsed An oprecht containing the number of true random snauwerig used to finish this request. bitsLeft An rechtschapen containing the (estimated) number of remaining true random onaardig available to the client. requestsLeft An oprecht containing the (estimated) number of remaining API requests available to the client. advisoryDelay An oprecht containing the recommended number of milliseconds that the client should delay before issuing another request.

For a successful response, the error property is absent.

Ordinary clients may not necessarily need all of the properties ter the response. A minimal client could use only the random.gegevens and advisoryDelay properties and disregard the surplus of the response.

Error Response

If an error occurred, RANDOM.ORG comebacks a JSON-RPC response ter which the result property is absent and the error property contains an error object spil described te Error Codes and Messages.

Example 1

The following requests four random numbers from a Gaussian distribution with mean 0.0 and standard deviation 1.0, accurate up to eight significant digits.

The service responds with the following:

The gegevens array within the result contains the true random numbers produced. Note that while eight significant digits are used, final zeroes after the parte points are not shown, making some numbers show up to have fewer significant digits. Also note that the completionTime specifies UTC time zone (‘Zulu time’) by the letterteken ‘Z’ after the clock time. Through the other fields ter the result object, RANDOM.ORG also advises how many true random vinnig were used to sate the request (106) and how many kattig (199,894) and requests (Five,442) are left te the client’s quota. It also advises the client that it can go ahead and punt the next request without delay (0 milliseconds).

Example Two

The following requests Two,000 random numbers from a Gaussian distribution with mean of 1,100 and standard deviation of 100, accurate up to four fracción places. This could be used to simulate the lifetimes of lightbulbs (measured ter hours), spil ter example Ten.Three.Five of Handbook of Statistical Distributions with Applications.

The service responds with the following:

The random object contains the true random numbers (te the gegevens array) produced, spil well spil the completion time.

The remaining fields ter the result object indicate how many true random kattig were used to please the request spil well spil how many kattig and requests are left te the client’s quota. The response also advises the client preferably to delay at least two seconds before issuing a fresh request.

Example Three

The following requests 100 random numbers from a Gaussian distribution with mean 140 and standard deviation Ten, accurate to six quebrado places.

The service responds with the following:

The random object contains the random gegevens generated by the server. For brevity, only the very first four values are shown ter the response. Spil ter example 1, final zeroes after the parte point are not shown.

The service also advises how many true random onaardig were used to sate the request and how many are left ter the client’s quota.

generateStrings

This method generates true random strings. Your client voorwaarde set the method property of its JSON-RPC request object to generateStrings . The request voorwaarde also contain an id member, which will be returned ter the response.

Required Parameters

The following parameters are mandatory and should be specified te the params array of the JSON-RPC request:

apiKey Your API key, which is used to track the true random bit usage for your client. n How many random strings you need. Vereiste be within the [1,1e4] range. length The length of each string. Voorwaarde be within the [1,20] range. All strings will be of the same length characters A string that contains the set of characters that are permitted to occur ter the random strings. The maximum number of characters is 80.

Optional Parameters

The following parameters are optional and can be included ter the params object of your JSON-RPC request if you want functionality that is different from the default:

replacement (default value true ) Specifies whether the random strings should be picked with replacement. The default ( true ) will cause the strings to be picked with replacement, i.e., the resulting list of strings may contain duplicates (like a series of dice rolls). If you want the strings to be unique (like raffle tickets drawn from a container), set this value to false .

Successful Response

If the strings were generated successfully, RANDOM.ORG comebacks a JSON-RPC response with the result property containing an object with the following named values:

random This object encapsulates the random numbers and associated gegevens. It contains the following properties. gegevens An array containing the strings requested. completionTime A string containing the timestamp te ISO 8601 format at which the request wasgoed finished. bitsUsed An rechtschapen containing the number of true random onverdraagzaam used to accomplish this request. bitsLeft An rechtschapen containing the (estimated) number of remaining true random vinnig available to the client. requestsLeft An oprecht containing the (estimated) number of remaining API requests available to the client. advisoryDelay An rechtschapen containing the recommended number of milliseconds that the client should delay before issuing another request.

For a successful response, the error property is absent.

Ordinary clients may not necessarily need all of the properties ter the response. A minimal client could use only the random.gegevens and advisoryDelay properties and disregard the surplus of the response.

Error Response

If an error occurred, RANDOM.ORG comebacks a JSON-RPC response ter which the result property is absent and the error property contains an error object spil described te Error Codes and Messages.

Example 1

The following requests eight strings of ten characters te length. Only lowercase characters from the English alphabet are permitted. The replacement parameter is set to true , which means the strings will be picked with replacement, i.e., can contain duplicate values.

The service responds with the following:

The gegevens array within the result contains the true random strings produced. Note that the completionTime specifies UTC time zone (‘Zulu time’) by the letterteken ‘Z’ after the clock time. Through the other fields te the result object, RANDOM.ORG also advises how many true random kattig were used to please the request (470) and how many onvriendelijk (199,530) and requests (9,999) are left ter the client’s quota. It also advises the client that it can go ahead and kwestie the next request without delay (0 milliseconds).

Example Two

The following requests ten strings of length eight. Allowable characters are all letters from the English alphabet (uppercase and lowercase letters are treated spil separate characters) spil well spil parte digits and a few special characters. The replacement parameter is set to false , meaning that strings will be generated without replacement, such that there will be no duplicates amongst them.

The service responds with the following:

The random object contains the true random strings (te the gegevens array) produced, spil well spil the completion time.

The remaining fields ter the result object indicate how many true random onvriendelijk were used to sate the request spil well spil how many onaardig and requests are left te the client’s quota. The response also advises the client preferably to delay at least two seconds before issuing a fresh request.

Example Three

The following requests sixteen strings of length four. All characters from the Danish and Norwegian alphabet are permitted. The replacement parameter is given, which means the service will use the default value of true and the strings will be picked with replacement, i.e., duplicates are permitted.

The service responds with the following:

The random object contains the random gegevens generated by the server. The service also advises how many true random onaardig were used to sate the request and how many kattig and requests are left ter the client’s quota.

generateUUIDs

This method generates version Four true random Universally Unique IDentifiers (UUIDs) ter accordance with section Four.Four of RFC 4122. Your client vereiste set the method property of its JSON-RPC request object to generateUUIDs . The request vereiste also contain an id member, which will be returned te the response.

Required Parameters

The following parameters are mandatory and should be specified ter the params array of the JSON-RPC request:

apiKey Your API key, which is used to track the true random bit usage for your client. n How many random UUIDs you need. Voorwaarde be within the [1,1e3] range.

Optional Parameters

This method has no optional parameters.

Successful Response

If the UUIDs were generated successfully, RANDOM.ORG comes back a JSON-RPC response with the result property containing an object with the following named values:

random This object encapsulates the random UUIDs and associated gegevens. It contains the following properties. gegevens An array containing the sequence of UUIDs requested, represented spil strings. completionTime A string containing the timestamp ter ISO 8601 format at which the request wasgoed ended. bitsUsed An oprecht containing the number of true random onvriendelijk used to finish this request. bitsLeft An rechtschapen containing the (estimated) number of remaining true random kattig available to the client. requestsLeft An rechtschapen containing the (estimated) number of remaining API requests available to the client. advisoryDelay An oprecht containing the recommended number of milliseconds that the client should delay before issuing another request.

For a successful response, the error property is absent.

Ordinary clients may not necessarily need all of the properties te the response. A minimal client could use only the random.gegevens and advisoryDelay properties and disregard the surplus of the response.

Error Response

If an error occurred, RANDOM.ORG comes back a JSON-RPC response ter which the result property is absent and the error property contains an error object spil described ter Error Codes and Messages.

Example 1

The following requests a single UUID.

The service responds with the following:

The gegevens array within the result contains the UUID produced. Note that the completionTime specifies UTC time zone (‘Zulu time’) by the letterteken ‘Z’ after the clock time. Through the other fields te the result object, RANDOM.ORG also advises how many true random kattig were used to please the request (122) and how many onvriendelijk (998,532) and requests (199,996) are left te the client’s quota. It also advises the client that it can go ahead and punt the next request after a brief delay (1 2nd).

Example Two

The following requests eight UUIDs.

The service responds with the following:

The random object contains the true random UUIDs (te the gegevens array) produced, spil well spil the completion time.

The remaining fields ter the result object indicate how many true random onaardig were used to please the request spil well spil how many onverdraagzaam and requests are left te the client’s quota. The response also advises the client can go ahead and kwestie the next request without delay.

generateBlobs

This method generates Binary Large OBjects (BLOBs) containing true random gegevens. Your client voorwaarde set the method property of its JSON-RPC request object to generateBlobs . The request voorwaarde also contain an id member, which will be returned te the response.

Required Parameters

The following parameters are mandatory and should be specified te the params array of the JSON-RPC request:

apiKey Your API key, which is used to track the true random bit usage for your client. n How many random blobs you need. Vereiste be within the [1,100] range. size The size of each blob, measured ter onvriendelijk. Vereiste be within the [1,1048576] range and vereiste be divisible by 8.

The total size of all blobs requested voorwaarde not exceed 1,048,576 onvriendelijk (128 KiB).

Optional Parameters

The following parameters are optional and can be included te the params object of your JSON-RPC request if you want functionality that is different from the default:

format (default value base64 ) Specifies the format te which the blobs will be returned. Values permitted are base64 and hex .

Successful Response

If the blobs were generated successfully, RANDOM.ORG comebacks a JSON-RPC response with the result property containing an object with the following named values:

random This object encapsulates the random blobs and associated gegevens. It contains the following properties. gegevens An array containing the blobs requested. Each blob will be formatted spil a string encoded te the format specified ter the request. completionTime A string containing the timestamp ter ISO 8601 format at which the request wasgoed ended. bitsUsed An oprecht containing the number of true random vinnig used to finish this request. bitsLeft An rechtschapen containing the (estimated) number of remaining true random onvriendelijk available to the client. requestsLeft An rechtschapen containing the (estimated) number of remaining API requests available to the client. advisoryDelay An rechtschapen containing the recommended number of milliseconds that the client should delay before issuing another request.

For a successful response, the error property is absent.

Ordinary clients may not necessarily need all of the properties ter the response. A minimal client could use only the random.gegevens and advisoryDelay properties and overlook the surplus of the response.

Error Response

If an error occurred, RANDOM.ORG comes back a JSON-RPC response ter which the result property is absent and the error property contains an error object spil described te Error Codes and Messages.

Example 1

The following requests a single blob containing 1,024 true random onverdraagzaam (128 bytes), for example to seed a pseudo-random number generator.

The service responds with the following:

The gegevens array within the result contains the random blob produced. Since no value wasgoed specified for the format parameter, the blob is encoded with the default base64-encoding. Note that the completionTime specifies UTC time zone (‘Zulu time’) by the letterteken ‘Z’ after the clock time. Through the other fields ter the result object, RANDOM.ORG also advises how many true random onverdraagzaam were used to please the request (1,024) and how many snauwerig (198,976) and requests (9,999) are left te the client’s quota. It also advises the client that it can go ahead and punt the next request without delay (0 milliseconds).

Example Two

The following requests four blobs, each containing 6,144 true random onverdraagzaam (768 bytes) encoded spil hex strings.

The service responds with the following:

The gegevens array within the result contains the random blobs produced, formatted spil hex strings. Note that the completionTime specifies UTC time zone (‘Zulu time’) by the letterteken ‘Z’ after the clock time. Through the other fields te the result object, RANDOM.ORG also advises how many true random onvriendelijk were used to sate the request (24,576) and how many onverdraagzaam (175,424) and requests (9,999) are left ter the client’s quota. It also advises the client that it can go ahead and punt the next request without delay (0 milliseconds).

getUsage

This method comes back information related to the the usage of a given API key. Your client vereiste set the method property of its JSON-RPC request object to getUsage . The request voorwaarde also contain an id member, which will be returned ter the response.

Required Parameters

The following parameters are mandatory and should be specified ter the params array of the JSON-RPC request:

apiKey Your API key, which is used to track the true random bit usage for your client.

Optional Parameters

This method has no optional parameters.

Successful Response

If the request succeeded, RANDOM.ORG comes back a JSON-RPC response with the result property containing an object with the following named values:

status A string indicating the API key’s current status, which may be stopped , paused or running . An API key vereiste be running for it to be able to serve requests. creationTime A string containing the timestamp te ISO 8601 format at which the API key wasgoed created. bitsLeft An oprecht containing the (estimated) number of remaining true random onaardig available to the client. requestsLeft An rechtschapen containing the (estimated) number of remaining API requests available to the client. totalBits An rechtschapen containing the number of onverdraagzaam used by this API key since it wasgoed created. totalRequests An oprecht containing the number of requests used by this API key since it wasgoed created.

For a successful response, the error property is absent.

Error Response

If an error occurred, RANDOM.ORG comes back a JSON-RPC response ter which the result property is absent and the error property contains an error object spil described te Error Codes and Messages.

Example 1

The following requests usage information for an API key that exists and is running.

The service responds with the following:

RANDOM.ORG informs that the API key ter question is running and advises how many onvriendelijk (998,532) and requests (199,996) are left te its quota. The response also contains information about how many onvriendelijk (1,646,421) and requests (65,036) have bot served with this API key since it wasgoed created (on 1 February 2013 at Five.53pm UTC).

Example Two

The following requests usage information for an API key that is paused.

The service responds with the following:

RANDOM.ORG advises that the API key te question exists but is paused, which means that it cannot be used to serve requests right now. The service also informs how many onaardig (871,365) and requests (199,977) are left te the quota for this API key. The response also contains information about how many onverdraagzaam (Three,519,123) and requests (Sixty nine,274) have bot served with this API key since it wasgoed created (on 1 February 2013 at Five.53pm UTC).

Example Trio

The following requests usage information for an API key that does not exist.

2 thoughts on “JSON-RPC API – Release 1 – Basic Methods

Leave a Reply

Your email address will not be published. Required fields are marked *