JSON-RPC Interface

Authentication

The examples from this section assume that the dim server URL is http://example.com/dim.

To access the JSON-RPC interface you must provide a valid session cookie. Failure to do so will result in a 403 HTTP response.

To get a session cookie, a HTTP POST request must be sent to /login with the following parameters:

  • username

  • password

Example:

POST /dim/login HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 35

username=username&password=password

A cookie will be set in the response:

Set-Cookie: session=eyJfcGVybWFuZW50IjpmYWxzZSwidXNlcm5hbWUiOiJkaW0ifQ.YSTEnQ.OPsFMPoZD7SsLmuAJNvRXH-MZZs; HttpOnly; Path=/

Tools

Tools that authenticate users and want to call DIM on behalf of them need to do a HTTP POST request to /login with the following parameters:

  • username

  • tool: the tool name

  • salt

  • sign: md5(username + salt + secret_key) where secret_key is the shared secret between DIM and the tool

Example

POST /dim/login HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 85

username=username&tool=toolname&salt=1394100619&sign=d0b0b73f15734c93a16c158dd1f14f55

where the shared secret is secretkey.

CAS

For CAS_ login, the frontend uses the /cas endpoint to check the ticket and generate the necessary cookie.

Protocol

The protocol used is JSON-RPC 2.0. Requests must be sent to /jsonrpc.

Example request for the call ipblock_get_attrs("12.0.0.1"):

POST /dim/jsonrpc HTTP/1.1
Host: example.com
Content-Type: application/json-rpc; charset=utf-8
Cookie: session=eyJfcGVybWFuZW50IjpmYWxzZSwidXNlcm5hbWUiOiJkaW0ifQ.YSTEnQ.OPsFMPoZD7SsLmuAJNvRXH-MZZs
Content-Length: 78

{"jsonrpc":"2.0","id":null,"method":"ipblock_get_attrs","params":["12.0.0.1"]}

Response:

HTTP/1.1 200 OK
Content-Type: application/json-rpc; charset=utf-8
Content-Length: 75

{"jsonrpc":"2.0","id":null,"result":{"status":"Available","ip":"12.0.0.1"}}

Another example for a call that returns an error:

  • JSON request: {"jsonrpc":"2.0","id":null,"method":"ipblock_get_attrs","params":["12.0.0.1a"]}

  • JSON response: {"jsonrpc":"2.0","error":{"message":"Invalid IP address: '12.0.0.1a'","code":1},"id":null}