Ably Specification: 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://ably.com/docs/core-features/authentication */
  ],
  namespaces: [
    /* Array of channel namespace rules
       See https://ably.com/docs/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.