Document batch publish support in /rest-api.

[SimonWoolf]

Currently we have no documentation for this besides https://gist.github.com/paddybyers/932cb484362713f52bfa762611b0b865 . We may not have immediate plans for integrating this into client libs proper (discussion proposal for that is ably/specification#64 ), but we should still document it on the rest-api page (possibly marked as beta) -- we've been pointing customers to it for a while now, so it's effectively a public api (ie we can't drastically change the interface without a reasonable deprecation period etc).

[mattheworiordan]

Hey @tomczoink I agree we should do this given it's trivial to do.
If you just take the content from https://gist.github.com/paddybyers/932cb484362713f52bfa762611b0b865#background onwards and put into a Textile file perhaps named "rest-api/experimental", with some basic context about the page containing only experimental APIs. Then you could add a note to the REST API documentation under publish about there being an experimental API available that supports batch publishing across multiple channels. Would be really nice in the experimental section to have a demo as well, perhaps just a simple JSBin using the request method?

[SimonWoolf]

Recording the text I've been sending to customers here (since the api had somewhat changed since Paddy wrote that exercise, and it contains a lot of stuff not relevant to the customer):

---

The batch publish endpoint is currently undocumented and not formally supported by the client lib, so to use it you need to use the Rest#request method, see https://www.ably.io/documentation/rest/usage#request .

You POST to /messages with a body of either a single batch spec or an array of batch specs, where a batch spec is an object of the form:

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

where:

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

Example 1:

{
  channels: ['a channel name, containing a comma', 'another channel name'],
  messages: {data: 'My message contents'}
}

Example 2:

{
  channels: 'single channel',
  messages: [
    {data: 'My message contents'},
    {name: 'an event', data: 'My event message contents'},
  ]
}

Example 3:

[
  {
    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'},
    ]
  }
]

Make sure your request body obeys the following restrictions:

• The total number of different channels used must be under 100
• The total size of the request body should be under 512kB

[paddybyers]

I think this description also needs examples of how to handle the different kinds of errors that arise (ie full vs partial errors).

[mattheworiordan]

@tomczoink can this issue be closed?