How to use ActionCable as API

Question

I built a very simple app using Rails 5 beta 1 and ActionCable to show when users come online and let them send messages to each other.

Now, I would basically like to take the client-side part of ActionCable, implement it in the context of another app (that does not run on Rails 5) and connect it with the first app to send and receive data (such as the online status of users or messages).

To send data from that second app, I assume, I can simply make an AJAX POST request. The question is: How do I subscribe from my second app to an open connection of the first app?

Or even: How do I subscribe to the ActionCable connection of my Rails app from another app via API?

My guess is, I essentially want to include this coffeescript somehow in my second app:

App.appearance = App.cable.subscriptions.create "AppearanceChannel",
  connected: ->
    # Called when the subscription is ready for use on the server

  disconnected: ->
    # Called when the subscription has been terminated by the server

  received: (data) ->
    # ...

Answer 1

You'll essentially need to include a copy or port of the ActionCable JS code in your other app (https://github.com/rails/rails/tree/master/actioncable/app/assets/javascripts).

Update: I recently released an npm package called actioncable-js that provides a direct port of Ruby on Rails 5's ActionCable CofeeScript to standard JS for use outside of Rails: https://github.com/mwalsher/actioncable-js

Because ActionCable is just a layer on top of HTML5 WebSockets, so you can also use raw WebSockets JS code (or any third-party library) to handle the messaging.

The ActionCable message protocol is somewhat documented here: https://github.com/NullVoxPopuli/action_cable_client#the-action-cable-protocol. I'll paste below for convenience:

1. Connect to the Action Cable URL

2. After the connection succeeds, send a subscribe message

   • The subscribe message JSON should look like this: {"command":"subscribe","identifier":"{\"channel\":\"MeshRelayChannel\"}"}
   • You should receive a message like this: {"identifier"=>"{\"channel\":\"MeshRelayChannel\"}", "type"=>"confirm_subscription"}

3. Once subscribed, you can send messages.

   • Make sure that the action string matches the data-handling method name on your ActionCable server.
   • Your message JSON should look like this: {"command":"message","identifier":"{\"channel\":\"MeshRelayChannel\"}","data":"{\"to\":\"user1\",\"message\":\"hello from user2\",\"action\":\"chat\"}"}
   • Received messages should look about the same

4. Notes:

   • Every message sent to the server has a command and identifier key.
   • The channel value must match the name of the channel class on the ActionCable server.
   • identifier and data are redundantly jsonified.

So, for example (in ruby)

payload = {
  command: 'command text',
  identifier: { channel: 'MeshRelayChannel' }.to_json,
  data: { to: 'user', message: 'hi', action: 'chat' }.to_json
}.to_json

Answer 2

While mwalsher's solution was extremely helpful to me, I recently found a pull request on the Rails repository with an official solution to my question.

https://github.com/rails/rails/pull/24991

I assume, in the near future this will be added to the main documentation. Here is the link to the official actioncable npm package: https://www.npmjs.com/package/actioncable

You can use it similar to mwalsher's solution with any JS app. Just install the npm package:

npm install actioncable --save

Here the JS example from the documentation:

ActionCable = require('actioncable')

var cable = ActionCable.createConsumer('wss://RAILS-API-PATH.com/cable')

cable.subscriptions.create('AppearanceChannel', {
  // normal channel code goes here...
});

Edit: The pull request has been merged for a while, now and the description is part of the official Readme - just not yet in the Rails Guides.