Please be aware that you are viewing our bleeding edge unstable documentation. Unless you wanted to view the bleeding edge (and possibly unstable) documentation, we recommend you use our stable docs.

Go to Ably's stable canonical documentation »

I know what I'm doing, let me see the bleeding edge docs »

You are viewing our bleeding edge unstable documentation. We recommend you use our stable documentation »
Fork me on GitHub

Sandbox Test API

Overview

All client libraries have test suites that by default will run their tests against temporary applications that are created during test setup. Although Ably does not provide a public provisioning API for account management (in the production system this is available only through the website registration and dashboard) there is a limited API provided via the REST
interface in the sandbox environment to enable test applications and keys to be provisioned. Therefore, all tests are set up to run against the special client-library focused sandbox environment.

Provisioning a new App

POST sandbox-rest.ably.io/apps

Provisioning a new app in the sandbox environment does not require any authentication, however the apps created have low message and connection limits and are automatically deleted soon after they are created. Apps created in the sandbox environment are designed to be used for client library tests only. If you require a sandbox app for your realtime application, you should provision an app from within your Ably dashboard that will be isolated from any other apps you have within your account, but will offer all the features and scalability of any production application.

The request body contains message details and is an object of the form:

{
  keys: [
    /* Array of requested API keys & capabilities
       See https://www.ably.io/documentation/general/authentication */
  ],
  namespaces: [
    /* Array of channel namespace rules
       See https://www.ably.io/documentation/general/channel-rules-namespaces */
  ],
  channels: [
    /* Array of fixture data to persist in history for tests */
    {
      "name": /* channel name String */
      "presence":[
        /* Array of member hashes on the channel with clientId and optional data */
      ]
    }
  ]
}

Example request:

curl -X POST https://sandbox-rest.ably.io/apps \
 -H "Content-Type: application/json" \
 --data '
  {
    "keys":[
      {},
      {
        "capability": "{ \"*\":[\"subscribe\",\"publish\"] }"
      },
      {
        "capability": "{ \"private\":[\"subscribe\",\"publish\"], \"chat\":[\"presence\"] }"
      }
    ],
    "namespaces":[
      { "id":"persisted", "persisted":true },
      { "id":"chat", "persisted":true }
    ],
    "channels":[
      {
        "name":"chat",
        "presence":[
          { "clientId":"John", "data":"john@test.com" },
          { "clientId":"Dave", "data":"dave@test.com" }
        ]
      }
    ]
  }'
Options
Content-Type
application/json default, or application/x-msgpack
Accept
application/json default, or application/x-msgpack
Auth required
no
Returns

Once the app, keys and associated fixture data is provisioned within the sandbox environment, a json_result with details on the app and keys for authentication is returned.

Example json_result:

{
  "status": 1,
  "created": 1427027306492,
  "modified": 1427027306492,
  "tlsOnly": false,
  "labels": "autodelete",
  "id": "RvMHnA:mO_fpQ",
  "appId": "mO_fpQ",
  "accountId": "RvMHnA",
  "keys": [
    {
      "id": "TfycQA",
      "scopeId": "app:mO_fpQ",
      "status": 0,
      "type": 0,
      "value": "z_Qclvo2g5hoZS49",
      "created": 1427027306880,
      "modified": 1427027306880,
      "capability": "{\"*\":[\"*\"]}",
      "expires": 1427030906880,
      "privileged": false
    },
    {
      "id": "JpfL9Q",
      "scopeId": "app:mO_fpQ",
      "status": 0,
      "type": 0,
      "value": "IgcN3ppcaB6STi8i",
      "created": 1427027306956,
      "modified": 1427027306956,
      "capability": "{\"*\":[\"publish\",\"subscribe\"]}",
      "expires": 1427030906956,
      "privileged": false
    },
    {
      "id": "y_BGvA",
      "scopeId": "app:mO_fpQ",
      "status": 0,
      "type": 0,
      "value": "VDAzscwkqMG3k6lF",
      "created": 1427027306957,
      "modified": 1427027306957,
      "capability": "{\"chat\":[\"presence\"],\"private\":[\"publish\",\"subscribe\"]}",
      "expires": 1427030906957,
      "privileged": false
    }
  ],
  "namespaces": [
    {
      "id": "persisted",
      "created": 1427027307112,
      "modified": 1427027307112,
      "persisted": true
    },
    {
      "id": "chat",
      "created": 1427027307117,
      "modified": 1427027307117,
      "persisted": true
    }
  ],
  "connections": [
    {
      "name": "sole",
      "key": "SxWts_hwr1vTKXWY"
    }
  ],
  "channels": [
    {
      "name": "chat",
      "presence": [
        {
          "clientId": "John",
          "data": "john@test.com"
        },
        {
          "clientId": "Dave",
          "data": "dave@test.com"
        }
      ],
      "connection": "sole"
    }
  ]
}

Creating stats fixture data

POST sandbox-rest.ably.io/stats

In order to streamline the development of client libraries, Ably provides a mechanism to inject stats fixture data into an application set up within the sandbox environment. Without this endpoint, to test statistics you have to generate real events and wait or the stats to become available (they are aggregrated in one minute intervals globally).

See application statistics for more information on the metrics available for each app.

Example request:

curl https://sandbox-rest.ably.io/stats \
  -H "Content-Type: application/json" \
  -u "[[API_KEY_FROM_APP_CREATION]]" \
  --data '[
  {
    "intervalId":"2014-02-03:15:03",
    "inbound": {
      "realtime": {
        "messages": {"count":50, "data":5000}
      }
    },
    "outbound": {
      "realtime": {
        "messages": {"count":20, "data":2000}
      }
    }
  },
  {
    "intervalId":"2014-02-03:15:04",
    "inbound": {
      "realtime": {
        "messages": {"count":70, "data":7000}
      }
    },
    "persisted": {
      "presence": {"count":20, "data":2000}
    },
    "connections": {
      "tls": {"peak":20, "opened":10}
    }
  }
]'
Options
Content-Type
application/json default, or application/x-msgpack
Accept
application/json default, or application/x-msgpack
Auth required
yes (basic or token)
Returns

Once the stats data has been persisted, the stats fixtures are returned in a json_result array.


Back to top