Delegation API (Release 3)

addDelegation (method)

This method creates a delegation of a particular service between two RANDOM.ORG account holders. Your client must set the method property of its JSON-RPC request object to addDelegation.

Required Parameters

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

credentials

Credentials that identify the delegator to RANDOM.ORG.

serviceId

Numeric ID of the service to be delegated.

delegateId

Numeric ID of the delegate.

Optional Parameters

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

notifyDelegate (default value true)

This value specify whether the delegate should be notified about the creation of the delegation. If the value is set to true, RANDOM.ORG will attempt to issue a notification. No error message is reported to the delegator if the notification fails or if no method for notification is configured for the delegate in question.

Successful Response

If the delegation was created successfully, RANDOM.ORG returns a JSON-RPC response with the result property containing an object with the following named values:

delegationKey

UUID identifying this delegation.

For a successful response, the error property is null.

If a delegation for the service in question already exists between the two parties, a successful response is returned with the existing delegationKey associated with that delegation. Adding an existing delegation in this manner will trigger a notification to the delegate if notifyDelegate was set to true in the request and the delegate has a requested such notifications.

Error Response

If an error occurred, RANDOM.ORG returns a JSON-RPC response in which the result property is null and the error property contains an error object as described in Error Codes and Messages.

Example 1

The following requests a delegation to be created between two RANDOM.ORG accounts in which the delegator (whose credentials are included in the request) gives the delegate (who has numeric account identifer 1012) the right to use the Third-Party Draw Service (which has service identifier 2) on their behalf.

{
    "jsonrpc": "2.0",
    "method": "addDelegation",
    "params": {
      "credentials": {
        "login": "test",
        "password": "secret"
      },
      "serviceId": 2,
      "delegateId": 1012
    },
    "id": 42
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
      "delegationKey": "b900f8ec-3812-4258-a659-ee2fcae431f0"
    },
    "error": null,
    "id": 42
}

Example 2

(to appear)

removeDelegation (method)

This method allows a delegator to remove a delegation, effectively revoking rights previously granted with the addDelegation method.

Required Parameters

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

credentials

Credentials that identify the delegator to RANDOM.ORG.

delegationKey

UUID identifying this delegation.

Optional Parameters

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

notifyDelegate (default value true)

This value specify whether the delegate should be notified about the removal of the delegation. If the value is set to true, RANDOM.ORG will attempt to issue a notification. No error message is reported to the delegator if the notification fails or if no method for notification is configured for the delegate in question.

Successful Response

If the delegation was removed successfully, RANDOM.ORG returns a JSON-RPC response with the result property containing an empty object.

For a successful response, the error property is null.

Error Response

If an error occurred, RANDOM.ORG returns a JSON-RPC response in which the result property is null and the error property contains an error object as described in Error Codes and Messages.

Example 1

The following requests removal of a delegation previously created between the two RANDOM.ORG account holders mentioned in the example above.

{
    "jsonrpc": "2.0",
    "method": "removeDelegation",
    "params": {
      "credentials": {
        "login": "test",
        "password": "secret"
      }
      "delegationKey": "b900f8ec-3812-4258-a659-ee2fcae431f0"
    },
    "id": 42
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {},
    "error": null,
    "id": 42
}

Example 2

(to appear)

listDelegations (method)

This method lets the caller list all delegations in which they act as delegator or delegate.

Required Parameters

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

credentials

Credentials that identify the caller to RANDOM.ORG.

Optional Parameters

There are no optional parameters.

Successful Response

If the operation completed successfully, RANDOM.ORG returns a JSON-RPC response with the result property containing an object with the following named values:

delegations

This array encapsulates the delegations in which the caller acts as delegator or delegate. Each delegation is an object containing the following values:

serviceId

The numeric identifier of the delegated service.

delegatorId

The numeric identifier of the delegator.

delegateId

The numeric identifier of the delegate.

delegationKey

UUID identifying this delegation.

For a successful response, the error property is null.

Error Response

If an error occurred, RANDOM.ORG returns a JSON-RPC response in which the result property is null and the error property contains an error object as described in Error Codes and Messages.

Example 1

The following requests a list of all delegations that relate to a particular RANDOM.ORG trial account:

{
    "jsonrpc": "2.0",
    "method": "listDelegations",
    "params": {
        "credentials": {
            "login": "test",
            "password": "secret"
        }
    },
    "id": 42
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "delegations": [
            {
                "serviceId": 2,
                "delegatorId": 3,
                "delegateId": 1012,
                "delegationKey": "b900f8ec-3812-4258-a659-ee2fcae431f0"
            },
            {
                "serviceId": 2,
                "delegatorId": 3,
                "delegateId": 5136,
                "delegationKey": "dc3faf78-bae1-4b42-a2a8-a54a39237afb"
            }
        ],
        "delegators": []
    },
    "error": null,
    "id": 42
}

The response shows that two delegations exist in which the caller participates. (The caller in the example has numeric ID 3, which is a trial account that belongs to RANDOM.ORG.) In both instances, it is the Third-Party Draw Service that is being delegated to other users, allowing those users to use the service on behalf of the trial account.

Example 2

(to appear)

setNotificationHandler (method)

This method allows a RANDOM.ORG account holder to register a handler that will be used to deliver notifications about the creation and deletion of delegations in which the account holder is delegate. The client must set the method property of its JSON-RPC request object to setNotificationHandler.

Required Parameters

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

credentials

Credentials that identify the delegator to RANDOM.ORG.

handlerUrl

A URL that will be be used to deliver notifications in the form of JSON-RPC 2.0 requests. The URL must use secure HTTP. The program residing at the URL must be able to handle the notifications described below. The caller can specify null for this parameter to delete any existing handler.

handlerSecret

A shared secret chosen by the caller. RANDOM.ORG will pass this secret back to the caller in all notifications. This allows the caller to verify the authenticity of the notifications.

Optional Parameters

There are no optional parameters.

Successful Response

If the handler was set correctly, RANDOM.ORG returns a JSON-RPC response with the result property containing an empty object.

For a successful response, the error property is null.

Error Response

If an error occurred, RANDOM.ORG returns a JSON-RPC response in which the result property is null and the error property contains an error object as described in Error Codes and Messages.

Example 1

The following sets a notification handler for the account in question.

{
    "jsonrpc": "2.0",
    "method": "setNotificationHandler",
    "params": {
      "credentials": {
        "login": "test",
        "password": "secret"
      },
      "handlerUrl": "https://api.example.com/rdo-notify/invoke",
      "handlerSecret": "insert-very-hard-to-guess-string-here"
    },
    "id": 42
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {},
    "error": null,
    "id": 42
}

Example 2

The following deletes any notification handler for the account in question. If no handler exists, this call has no effect.

{
    "jsonrpc": "2.0",
    "method": "setNotificationHandler",
    "params": {
      "credentials": {
        "login": "test",
        "password": "secret"
      },
      "handlerUrl": null,
      "handlerSecret": null
    },
    "id": 42
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {},
    "error": null,
    "id": 42
}

delegationAdded (notification)

This method must be exposed by a RANDOM.ORG account holder who wishes to receive notifications about the addition of delegations where the account holder is delegate. Upon such a change in delegation, RANDOM.ORG will invoke the client's registered notification handler to deliver the notification. RANDOM.ORG will set the method property of its JSON-RPC request object to delegationAdded.

Required Parameters

The following parameters are mandatory and will be specified in the params array of the JSON-RPC request issued by RANDOM.ORG:

serviceId

Numeric ID of the service being delegated.

delegatorId

Numeric ID of the delegator.

delegateId

Numeric ID of the delegate. (The presence of this value in the notification allows the same handler to serve multiple delegates.)

delegationKey

UUID identifying this delegation.

handlerSecret

The shared secret chosen by the delegate when it configured its notification handler. RANDOM.ORG passes the secret back to the delegate to allow them to verify the authenticity of the notification.

Optional Parameters

There are no optional parameters.

Successful Response

If notification was delivered successfully, the notification handler should return a JSON-RPC response with the result property containing an empty object.

For a successful response, the error property should be set to null.

Error Response

If an error occurred, the notification handler should return a JSON-RPC response in which the result property is null and the error property contains a textual description of what went wrong. RANDOM.ORG may then try to deliver the notification again later on.

Example 1

The following is a request issued by RANDOM.ORG after the creation of a delegation in which the delegator (who has numeric account identifier 3) gives the delegate (who has numeric account identifer 1012) the right to use the Third-Party Draw Service (which has service identifier 2) on their behalf.

{
    "jsonrpc": "2.0",
    "method": "delegationAdded",
    "params": {
      "serviceId": 2,
      "delegatorId": 3,
      "delegateId": 1012,
      "delegationKey": "b900f8ec-3812-4258-a659-ee2fcae431f0",
      "handlerSecret": "insert-very-hard-to-guess-string-here"
    },
    "id": 42
}

To indicate successful acceptance of the notification, the notification handler should respond with the following:

{
    "jsonrpc": "2.0",
    "result": {},
    "error": null,
    "id": 42
}

Because this is a response that indicates successful delivery of the notification, RANDOM.ORG will not retry the delivery again later.

Example 2

The following is the same request as in the previous example. However, in this case, we assume the notification handler is not able to accept the notification:

{
    "jsonrpc": "2.0",
    "method": "delegationAdded",
    "params": {
      "serviceId": 2,
      "delegatorId": 3,
      "delegateId": 1012,
      "delegationKey": "b900f8ec-3812-4258-a659-ee2fcae431f0",
      "handlerSecret": "insert-very-hard-to-guess-string-here"
    },
    "id": 42
}

To indicate unsuccessful acceptance of the notification, the notification handler should respond with the following:

{
    "jsonrpc": "2.0",
    "result": null,
    "error": "Unknown error; please retry later.",
    "id": 42
}

Because this is a response that indicates failed delivery of the notification, RANDOM.ORG may retry the notification again later.

delegationRemoved (notification)

This method must be exposed by a RANDOM.ORG account holder who wishes to receive notifications about the removal of delegations where the account holder is delegate. Upon such a change in delegation, RANDOM.ORG will invoke the client's registered notification handler to deliver the notification. RANDOM.ORG will set the method property of its JSON-RPC request object to delegationRemoved.

Required Parameters

The following parameters are mandatory and will be specified in the params array of the JSON-RPC request issued by RANDOM.ORG:

serviceId

Numeric ID of the service being delegated.

delegatorId

Numeric ID of the delegator.

delegateId

Numeric ID of the delegate. (The presence of this value in the notification allows the same handler to serve multiple delegates.)

delegationKey

UUID identifying this delegation.

handlerSecret

The shared secret chosen by the delegate when it configured its notification handler. RANDOM.ORG passes the secret back to the delegate to allow them to verify the authenticity of the notification.

Optional Parameters

There are no optional parameters.

Successful Response

If notification was delivered successfully, the notification handler should return a JSON-RPC response with the result property containing an empty object.

For a successful response, the error property should be set to null.

Error Response

If an error occurred, the notification handler should return a JSON-RPC response in which the result property is null and the error property contains a textual description of what went wrong. RANDOM.ORG may then try to deliver the notification again later on.

Example 1

The following is a request issued by RANDOM.ORG after the creation of a delegation in which the delegator (who has numeric account identifier 3) gives the delegate (who has numeric account identifer 1012) the right to use the Third-Party Draw Service (which has service identifier 2) on their behalf.

{
    "jsonrpc": "2.0",
    "method": "delegationRemoved",
    "params": {
      "serviceId": 2,
      "delegatorId": 3,
      "delegateId": 1012,
      "delegationKey": "b900f8ec-3812-4258-a659-ee2fcae431f0",
      "handlerSecret": "insert-very-hard-to-guess-string-here"
    },
    "id": 42
}

To indicate successful acceptance of the notification, the notification handler should respond with the following:

{
    "jsonrpc": "2.0",
    "result": {},
    "error": null,
    "id": 42
}

Because this is a response that indicates successful delivery of the notification, RANDOM.ORG will not retry the delivery again later.

Example 2

The following is the same request as in the previous example. However, in this case, we assume the notification handler is not able to accept the notification:

{
    "jsonrpc": "2.0",
    "method": "delegationRemoved",
    "params": {
      "serviceId": 2,
      "delegatorId": 3,
      "delegateId": 1012,
      "delegationKey": "b900f8ec-3812-4258-a659-ee2fcae431f0",
      "handlerSecret": "insert-very-hard-to-guess-string-here"
    },
    "id": 42
}

To indicate unsuccessful acceptance of the notification, the notification handler should respond with the following:

{
    "jsonrpc": "2.0",
    "result": null,
    "error": "Unknown error; please retry later.",
    "id": 42
}

Because this is a response that indicates failed delivery of the notification, RANDOM.ORG may retry the notification again later.