Ably is the platform that powers synchronized digital experiences in realtime. Whether attending an event in a virtual venue, receiving realtime financial information, or monitoring live car performance data – consumers simply expect realtime digital experiences as standard. Ably provides a suite of APIs to build, extend, and deliver powerful digital experiences in realtime for more than 250 million devices across 80 countries each month. Organizations like Bloomberg, HubSpot, Verizon, and Hopin depend on Ably’s platform to offload the growing complexity of business-critical realtime data synchronization at global scale. For more information, see the Ably documentation.
This is a Ruby REST client library for Ably. The library currently targets the Ably 1.1 client library specification. You can jump to the 'Known Limitations' section to see the features this client library does not yet support or view our client library SDKs feature support matrix to see the list of all the available features.
Visit https://www.ably.io/documentation for a complete API reference and more examples. The examples and API below is not exhaustive, you should use the completely Ably API documentation.
This REST only library was created for developers who do not want EventMachine as a dependency of their application. Typically developers who are using Ably within their Rails or Sinatra apps would prefer to use the REST library as it has less dependencies and offers a synchronous API.
If however you need to use a realtime library that offers an asynchronous evented AP, then we recommended you take a look at the combined REST & Realtime gem.
This client library is currently not compatible with some of the Ably features:
| Feature |
|---|
| Custom transportParams |
The client library is available as a gem from RubyGems.org.
Add this line to your application's Gemfile:
gem 'ably-rest'
And then execute:
$ bundle
Or install it yourself as:
$ gem install ably-rest
All examples assume a client and/or channel has been created as follows:
client = Ably::Rest.new(key: 'xxxxx')
channel = client.channel('test')channel.publish('myEvent', 'Hello!') #=> truemessages_page = channel.history #=> #<Ably::Models::PaginatedResult ...>
messages_page.items.first #=> #<Ably::Models::Message ...>
messages_page.items.first.data # payload for the message
messages_page.next # retrieves the next page => #<Ably::Models::PaginatedResult ...>
messages_page.has_next? # false, there are more pagesmembers_page = channel.presence.get # => #<Ably::Models::PaginatedResult ...>
members_page.items.first # first member present in this page => #<Ably::Models::PresenceMessage ...>
members_page.items.first.client_id # client ID of first member present
members_page.next # retrieves the next page => #<Ably::Models::PaginatedResult ...>
members_page.has_next? # false, there are more pagespresence_page = channel.presence.history #=> #<Ably::Models::PaginatedResult ...>
presence_page.items.first #=> #<Ably::Models::PresenceMessage ...>
presence_page.items.first.client_id # client ID of first member
presence_page.next # retrieves the next page => #<Ably::Models::PaginatedResult ...>When a 128 bit or 256 bit key is provided to the library, all payloads are encrypted and decrypted automatically using that key on the channel. The secret key is never transmitted to Ably and thus it is the developer's responsibility to distribute a secret key to both publishers and subscribers.
secret_key = Ably::Util::Crypto.generate_random_key
channel = client.channels.get('test', cipher: { key: secret_key })
channel.publish nil, "sensitive data" # data will be encrypted before publish
messages_page = channel.history
messages_page.items.first.data #=> "sensitive data"Tokens are issued by Ably and are readily usable by any client to connect to Ably:
token_details = client.auth.request_token
# => #<Ably::Models::TokenDetails ...>
token_details.token # => "xVLyHw.CLchevH3hF....MDh9ZC_Q"
client = Ably::Rest.new(token: token_details)Token requests are issued by your servers and signed using your private API key. This is the preferred method of authentication as no secrets are ever shared, and the token request can be issued to trusted clients without communicating with Ably.
token_request = client.auth.create_token_request(ttl: 3600, client_id: 'jim')
# => {"id"=>...,
# "clientId"=>"jim",
# "ttl"=>3600,
# "timestamp"=>...,
# "capability"=>"{\"*\":[\"*\"]}",
# "nonce"=>...,
# "mac"=>...}
client = Ably::Rest.new(token: token_request)stats_page = client.stats #=> #<Ably::Models::PaginatedResult ...>
stats_page.items.first = #<Ably::Models::Stats ...>
stats_page.next # retrieves the next page => #<Ably::Models::PaginatedResult ...>client.time #=> 2013-12-12 14:23:34 +0000Please visit http://support.ably.io/ for access to our knowledgebase and to ask for any assistance.
You can also view the community reported Github issues.
To see what has changed in recent versions of Bundler, see the CHANGELOG.
Please note that the bulk of this repo is in fact a submodule of the Ably Ruby REST & Realtime library. If you want to issue a PR, it is likely you should be looking in that repo to add features or make contributions.
- Fork it
- When pulling to local, make sure to also pull submodules (git submodule init && git submodule update)
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Ensure you have added suitable tests and the test suite is passing(
bundle exec rspec) - Push to the branch (
git push origin my-new-feature) - Create a new Pull Request
- Create a branch for the release, named like
release/1.2.3(where1.2.3is the new version number) - Change dir to
cd lib/submodules/ably-rubyandgit fetch origin && git fetch --tags - Reset to the tagged version released in ably-ruby, e.g.
git reset v1.2.3 --hard - Ensure submodules of this submodule are up to date using
git submodule update - Change dir back to root /
ably-ruby-rest - Stage changes made at submodule file
git add lib/submodules/ably-ruby - Commit the change
git commit -m "Version upgrade to v1.2.3"and push the changes. - Make a PR against
main. Once the PR is approved, merge it intomain - Add a tag to the new
mainhead commit and push to origin such asgit tag v1.2.3 && git push origin v1.2.3 - Visit https://github.com/ably/ably-ruby/tags and
Add release notesfor the release including links to the changelog entry. - Run
rake releaseto publish the gem to Rubygems
See the Ably Ruby release process notes.
Copyright (c) 2017 Ably Real-time Ltd, Licensed under the Apache License, Version 2.0. Refer to LICENSE for the license terms.