REST API Beta Features

REST API Beta Features

The contents of this section are beta features of our REST API. Although many of these features are fully functional, until the feature is released as generally available, the APIs may change. We recommend customers get in touch if they want to use these features in production.

Features

Batch publish

Batch mode is a way of querying an API multiple times with a single HTTP request. The simplest example to consider is publishing a single message to multiple channels; a single request is made, indicating the channels and the contents of the message, and the system attempts to publish on all channels in parallel. Each of those attempts may succeed or fail independently. The batch mode API provides a way for the results of that request to be indicated back to the caller.

Generic operation

A batch mode request translates a single set of request details (ie the request body, params and headers) in to an array of requests for the underlying API. Each of those requests is then performed in parallel.

Once each request has completed, the batch-mode response is formulated to be returned to the caller. There are three possible outcomes:

  • all requests succeeded. This is of course the expected case. The response is then an array containing the responses to the constituent queries in request order.
  • the batch request failed prior to attempting the constituent API calls. This could typically be an authorisation failure, an invalid request, or some required element of the service being unavailable. The response is then an error response, with the applicable status code and error response body (with message, code and any other relevant error information.
  • one or more constituent API calls failed. In this case the response contains a generic 400 status code and the response body contains an error object with a specific error code 40020 signifying an error in a batch operation. The error body also then contains a batchResponse property which in an array, in request order, containing the outcome of each of the constituent API calls.
    This means that caller can usually make the call and have access to the success result or an error in the case of failure. In the case of a partial failure, many callers may just wish to know whether or not the call succeeded fully, in which case they do not need to look at the batchResponse detail. However, callers that wish to know the detail of the outcome of each call can discover this from the batchResponse.

Bulk publish

The REST API has been extended to include batch-mode publish operations. The API concerned is:

POST /messages

This is the new bulk publish API which is implicitly a batch-mode API. This performs a publish in parallel of messages to channels specified in the request body. Check out the code example below on how to do this with the request method in the REST client library.

var ablyRest = new Ably.Rest({ key: 'xVLyHw.-lamXg:9EZfM-XY5ycFIZU5' })
var content = { "channels": [ "test1", "test2" ], "messages": { "data": 'myData' } }
ablyRest.request('post', '/messages', null, content, 
function(err, response) {
  if(err) {
    alert('An error occurred; err = ' + err.toString());
  } else {
    alert('Success! status code was ' + response.statusCode);
  }
});

You can also use the REST API directly with the following:

curl -X POST https://rest.ably.io/messages \
    -u "xVLyHw.-lamXg:9EZfM-XY5ycFIZU5" \
    -H "Content-Type: application/json" \
    --data '{ "channels": [ "test1", "test2"], 
"messages": {"data": "My test message text" } }'

A single BatchSpec is an object of the form:

{
  channels: <channel names>,
  messages: <messages>
}

where:

  • <channel names> is a single channel name String, or an Array of channel name Strings; and
  • <messages> is a single Message, or an Array of Messages.

The bulk publish endpoint accepts a request body containing either a single BatchSpec object, or an array of BatchSpec objects.

Therefore the following are all valid request bodies for a bulk publish request:

Using a single BatchSpec object
{
  channels: ['a channel name, containing a comma', 'another channel name'],
  messages: {data: 'My message contents'}
}
Using multiple BatchSpec objects in an array
[
  {
    channels: ['a channel name, containing a comma', 'another channel name'],
    messages: {data: 'My message contents'}
  },
  {
    channels: 'single channel',
    messages: [
      {data: 'My message contents'},
      {name: 'an event', data: 'My event message contents'},
    ]
  }
]

There is an obvious mapping from the request body to the array of individual publish requests.

Batch reponses

The request

POST /messages
{
  channels: ['channel0', 'channel1', 'channel2'],
  messages: {data: 'My test message text'}
}

would have the following possible outcomes:

Success:

status code: 201
response body:
[
  {
    "channel":"channel0",
    "messageId":"w234r5t-fr5"
  },
  {
    "channel":"channel1",
    "messageId":"vde4sfc0p"
  },
  {
    "channel":"channel2",
    "messageId":"nh3exv8ih"
  }
]

Common-cause failure:

status code: 401
response body:
{
  "error": {
    "message":"Token expired",
    "statusCode":401,
    "code":40140
  }
}


Partial success:
status code: 400
response body
{
  "error": {
    "message": "Batched response includes errors",
    "statusCode":400,
    "code":40020
  }
  "batchResponse": [
    {
      "data": {
        "channel":"channel0",
        "messageId":"w234r5t-fr5"
      }
    },
    {
      "data": {
        "channel":"channel1",
        "messageId":"vde4sfc0p"
      }
    },
    {
      "error": {
        "message": "Given credentials do not have the required capability",
        "statusCode": 401,
        "code": 40160
      }
    }
  ]
}

API reference
Documentation

Ready to get started?

Our free plan includes 3m messages per month, 100 peak connections, 100 peak channels, and loads of features.