Ably convention uses key: option to instance library, not api_key:

README.md

@@ -41,7 +41,7 @@ end
 All examples assume a client has been created as follows:
 
 ```ruby
-client = Ably::Realtime.new(api_key: 'xxxxx')
+client = Ably::Realtime.new(key: 'xxxxx')
 ```
 
 ### Connection
@@ -134,7 +134,7 @@ Unlike the Realtime API, all calls are synchronous and are not run within an [Ev
 All examples assume a client and/or channel has been created as follows:
 
 ```ruby
-client = Ably::Rest.new(api_key: 'xxxxx')
+client = Ably::Rest.new(key: 'xxxxx')
 channel = client.channel('test')
 ```
 

lib/ably/auth.rb

@@ -15,7 +15,7 @@ module Ably
   #   @return [Ably::Models::Token] Current {Ably::Models::Token} issued by this library or one of the provided callbacks used to authenticate requests
   # @!attribute [r] token_id
   #   @return [String] Token ID provided to the {Ably::Client} constructor that is used to authenticate all requests
-  # @!attribute [r] api_key
+  # @!attribute [r] key
   #   @return [String] Complete API key containing both the key ID and key secret, if present
   # @!attribute [r] key_id
   #   @return [String] Key ID (public part of the API key), if present
@@ -49,14 +49,16 @@ def initialize(client, options, &token_request_block)
         raise ArgumentError, 'Expected auth_options to be a Hash'
       end
 
-      if auth_options[:api_key] && (auth_options[:key_secret] || auth_options[:key_id])
-        raise ArgumentError, 'api_key and key_id or key_secret are mutually exclusive. Provider either an api_key or key_id & key_secret'
+      api_key = auth_options[:key] || auth_options[:api_key] # backwards support for previously used :api_key
+
+      if api_key && (auth_options[:key_secret] || auth_options[:key_id])
+        raise ArgumentError, 'key and key_id or key_secret are mutually exclusive. Provider either a key or key_id & key_secret'
       end
 
-      split_api_key_into_key_and_secret! auth_options if auth_options[:api_key]
+      split_api_key_into_key_and_secret! auth_options if api_key
 
       if using_basic_auth? && !api_key_present?
-        raise ArgumentError, 'api_key is missing. Either an API key, token, or token auth method must be provided'
+        raise ArgumentError, 'key is missing. Either an API key, token, or token auth method must be provided'
       end
 
       if has_client_id?
@@ -73,7 +75,7 @@ def initialize(client, options, &token_request_block)
     #
     # @param [Hash] options the options for the token request
     # @option options (see #request_token)
-    # @option options [String]  :api_key API key comprising the key ID and key secret in a single string
+    # @option options [String]  :key     API key comprising the key ID and key secret in a single string
     # @option options [Boolean] :force   obtains a new token even if the current token is valid
     #
     # @yield (see #request_token)
@@ -84,7 +86,7 @@ def initialize(client, options, &token_request_block)
     #
     # @example
     #    # will issue a simple token request using basic auth
-    #    client = Ably::Rest::Client.new(api_key: 'key.id:secret')
+    #    client = Ably::Rest::Client.new(key: 'key.id:secret')
     #    token = client.auth.authorise
     #
     #    # will use token request from block to authorise if not already authorised
@@ -99,7 +101,9 @@ def authorise(options = {}, &token_request_block)
       end
 
       options = options.clone
-      split_api_key_into_key_and_secret! options if options[:api_key]
+
+      api_key = options[:key] || options[:api_key] # backwards support for previously used :api_key
+      split_api_key_into_key_and_secret! options if api_key
 
       @options             = @options.merge(options)
       @default_token_block = token_request_block if block_given?
@@ -131,7 +135,7 @@ def authorise(options = {}, &token_request_block)
     #
     # @example
     #    # simple token request using basic auth
-    #    client = Ably::Rest::Client.new(api_key: 'key.id:secret')
+    #    client = Ably::Rest::Client.new(key: 'key.id:secret')
     #    token = client.auth.request_token
     #
     #    # token request using auth block
@@ -225,7 +229,7 @@ def create_token_request(options = {})
       convert_to_mixed_case_hash(token_request)
     end
 
-    def api_key
+    def key
       "#{key_id}:#{key_secret}" if api_key_present?
     end
 
@@ -308,12 +312,12 @@ def ensure_api_key_sent_over_secure_connection
     # Basic Auth HTTP Authorization header value
     def basic_auth_header
       ensure_api_key_sent_over_secure_connection
-      "Basic #{encode64("#{api_key}")}"
+      "Basic #{encode64("#{key}")}"
     end
 
     def split_api_key_into_key_and_secret!(options)
-      api_key_parts = options[:api_key].to_s.match(/(?<id>[\w_-]+\.[\w_-]+):(?<secret>[\w_-]+)/)
-      raise ArgumentError, 'api_key is invalid' unless api_key_parts
+      api_key_parts = (options[:key] || options[:api_key]).to_s.match(/(?<id>[\w_-]+\.[\w_-]+):(?<secret>[\w_-]+)/)
+      raise ArgumentError, 'key is invalid' unless api_key_parts
 
       options[:key_id]     = api_key_parts[:id].encode(Encoding::UTF_8)
       options[:key_secret] = api_key_parts[:secret].encode(Encoding::UTF_8)

lib/ably/realtime.rb

@@ -50,7 +50,7 @@ module Realtime
     #    client = Ably::Realtime.new('key.id:secret')
     #
     #    # create a new client authenticating with basic auth and a client_id
-    #    client = Ably::Realtime.new(api_key: 'key.id:secret', client_id: 'john')
+    #    client = Ably::Realtime.new(key: 'key.id:secret', client_id: 'john')
     #
     def self.new(options, &token_request_block)
       Ably::Realtime::Client.new(options, &token_request_block)

lib/ably/realtime/client.rb

@@ -75,7 +75,7 @@ class Client
       #    client = Ably::Realtime::Client.new('key.id:secret')
       #
       #    # create a new client and configure a client ID used for presence
-      #    client = Ably::Realtime::Client.new(api_key: 'key.id:secret', client_id: 'john')
+      #    client = Ably::Realtime::Client.new(key: 'key.id:secret', client_id: 'john')
       #
       def initialize(options, &token_request_block)
         @rest_client           = Ably::Rest::Client.new(options, &token_request_block)

lib/ably/realtime/connection.rb

@@ -150,7 +150,7 @@ def connect(&success_block)
       # @yield [Integer] if a block is passed to this method, then this block will be called once the ping heartbeat is received with the time elapsed in milliseconds
       #
       # @example
-      #    client = Ably::Rest::Client.new(api_key: 'key.id:secret')
+      #    client = Ably::Rest::Client.new(key: 'key.id:secret')
       #    client.connection.ping do |ms_elapsed|
       #      puts "Ping took #{ms_elapsed}ms"
       #    end

lib/ably/rest.rb

@@ -34,7 +34,7 @@ module Rest
     #    client = Ably::Rest.new('key.id:secret')
     #
     #    # create a new client authenticating with basic auth and a client_id
-    #    client = Ably::Rest.new(api_key: 'key.id:secret', client_id: 'john')
+    #    client = Ably::Rest.new(key: 'key.id:secret', client_id: 'john')
     #
     def self.new(options, &token_request_block)
       Ably::Rest::Client.new(options, &token_request_block)

lib/ably/rest/client.rb

@@ -70,7 +70,7 @@ class Client
       # @param [Hash,String] options an options Hash used to configure the client and the authentication, or String with an API key or Token ID
       # @option options (see Ably::Auth#authorise)
       # @option options [Boolean]                 :tls                 TLS is used by default, providing a value of false disables TLS.  Please note Basic Auth is disallowed without TLS as secrets cannot be transmitted over unsecured connections.
-      # @option options [String]                  :api_key             API key comprising the key ID and key secret in a single string
+      # @option options [String]                  :key                 API key comprising the key ID and key secret in a single string
       # @option options [Boolean]                 :use_token_auth      Will force Basic Auth if set to false, and TOken auth if set to true
       # @option options [String]                  :environment         Specify 'sandbox' when testing the client library against an alternate Ably environment
       # @option options [Symbol]                  :protocol            Protocol used to communicate with Ably, :json and :msgpack currently supported. Defaults to :msgpack
@@ -89,15 +89,15 @@ class Client
       #    client = Ably::Rest::Client.new('key.id:secret')
       #
       #    # create a new client and configure a client ID used for presence
-      #    client = Ably::Rest::Client.new(api_key: 'key.id:secret', client_id: 'john')
+      #    client = Ably::Rest::Client.new(key: 'key.id:secret', client_id: 'john')
       #
       def initialize(options, &token_request_block)
         raise ArgumentError, 'Options Hash is expected' if options.nil?
 
         options = options.clone
         if options.kind_of?(String)
           options = if options.match(/^[\w]{2,}\.[\w]{2,}:[\w]{2,}$/)
-            { api_key:  options }
+            { key: options }
           else
             { token_id: options }
           end

spec/acceptance/realtime/channel_history_spec.rb

@@ -3,7 +3,7 @@
 
 describe Ably::Realtime::Channel, '#history', :event_machine do
   vary_by_protocol do
-    let(:default_options) { options.merge(api_key: api_key, environment: environment, protocol: protocol) }
+    let(:default_options) { options.merge(key: api_key, environment: environment, protocol: protocol) }
 
     let(:client)       { Ably::Realtime::Client.new(default_options) }
     let(:channel)      { client.channel(channel_name) }

spec/acceptance/realtime/channel_spec.rb

@@ -3,7 +3,7 @@
 
 describe Ably::Realtime::Channel, :event_machine do
   vary_by_protocol do
-    let(:default_options) { { api_key: api_key, environment: environment, protocol: protocol } }
+    let(:default_options) { { key: api_key, environment: environment, protocol: protocol } }
     let(:client_options)  { default_options }
 
     let(:client)       { Ably::Realtime::Client.new(client_options) }
@@ -158,7 +158,7 @@
 
       context 'failure as a result of insufficient key permissions' do
         let(:restricted_client) do
-          Ably::Realtime::Client.new(default_options.merge(api_key: restricted_api_key, log_level: :fatal))
+          Ably::Realtime::Client.new(default_options.merge(key: restricted_api_key, log_level: :fatal))
         end
         let(:restricted_channel) { restricted_client.channel("cannot_subscribe") }
 
@@ -202,7 +202,7 @@
             restricted_channel.once(:failed) do
               restricted_client.close do
                 # A direct call to #authorise is synchronous
-                restricted_client.auth.authorise(api_key: api_key)
+                restricted_client.auth.authorise(key: api_key)
 
                 restricted_client.connect do
                   restricted_channel.once(:attached) do

spec/acceptance/realtime/client_spec.rb

@@ -4,7 +4,7 @@
 describe Ably::Realtime::Client, :event_machine do
   vary_by_protocol do
     let(:default_options) do
-      { api_key: api_key, environment: environment, protocol: protocol }
+      { key: api_key, environment: environment, protocol: protocol }
     end
 
     let(:client_options) { default_options }
@@ -15,7 +15,7 @@
 
     context 'initialization' do
       context 'basic auth' do
-        it 'is enabled by default with a provided :api_key option' do
+        it 'is enabled by default with a provided :key option' do
           connection.on(:connected) do
             expect(auth_params[:key_id]).to_not be_nil
             expect(auth_params[:access_token]).to be_nil
@@ -58,7 +58,7 @@
               end
             end
 
-            context 'with valid :api_key and :use_token_auth option set to true' do
+            context 'with valid :key and :use_token_auth option set to true' do
               let(:client_options)  { default_options.merge(use_token_auth: true) }
 
               it 'automatically authorises on connect and generates a token' do

spec/acceptance/realtime/connection_failures_spec.rb

@@ -6,7 +6,7 @@
 
   vary_by_protocol do
     let(:default_options) do
-      { api_key: api_key, environment: environment, protocol: protocol }
+      { key: api_key, environment: environment, protocol: protocol }
     end
 
     let(:client_options) { default_options }
@@ -16,7 +16,7 @@
 
     context 'authentication failure' do
       let(:client_options) do
-        default_options.merge(api_key: invalid_key, log_level: :none)
+        default_options.merge(key: invalid_key, log_level: :none)
       end
 
       context 'when API key is invalid' do

spec/acceptance/realtime/connection_spec.rb

@@ -7,7 +7,7 @@
 
   vary_by_protocol do
     let(:default_options) do
-      { api_key: api_key, environment: environment, protocol: protocol }
+      { key: api_key, environment: environment, protocol: protocol }
     end
 
     let(:client_options) { default_options }
@@ -177,7 +177,7 @@
             end
 
             context 'opening a new connection' do
-              let(:client_options) { default_options.merge(api_key: nil, token_id: expired_token.id, log_level: :none) }
+              let(:client_options) { default_options.merge(key: nil, token_id: expired_token.id, log_level: :none) }
 
               it 'transitions state to failed', em_timeout: 10 do
                 EventMachine.add_timer(1) do # wait for token to expire

spec/acceptance/realtime/message_spec.rb

@@ -6,7 +6,7 @@
 
 describe 'Ably::Realtime::Channel Message', :event_machine do
   vary_by_protocol do
-    let(:default_options) { options.merge(api_key: api_key, environment: environment, protocol: protocol) }
+    let(:default_options) { options.merge(key: api_key, environment: environment, protocol: protocol) }
     let(:client_options)  { default_options }
     let(:client) do
       Ably::Realtime::Client.new(client_options)
@@ -175,7 +175,7 @@
 
     context 'without suitable publishing permissions' do
       let(:restricted_client) do
-        Ably::Realtime::Client.new(options.merge(api_key: restricted_api_key, environment: environment, protocol: protocol))
+        Ably::Realtime::Client.new(options.merge(key: restricted_api_key, environment: environment, protocol: protocol))
       end
       let(:restricted_channel) { restricted_client.channel("cansubscribe:example") }
       let(:payload)            { 'Test message without permission to publish' }

spec/acceptance/realtime/presence_history_spec.rb

@@ -3,7 +3,7 @@
 
 describe Ably::Realtime::Presence, 'history', :event_machine do
   vary_by_protocol do
-    let(:default_options)     { { api_key: api_key, environment: environment, protocol: protocol } }
+    let(:default_options)     { { key: api_key, environment: environment, protocol: protocol } }
 
     let(:channel_name)        { "persisted:#{random_str(2)}" }
 

spec/acceptance/realtime/presence_spec.rb

@@ -5,7 +5,7 @@
   include Ably::Modules::Conversions
 
   vary_by_protocol do
-    let(:default_options) { { api_key: api_key, environment: environment, protocol: protocol } }
+    let(:default_options) { { key: api_key, environment: environment, protocol: protocol } }
     let(:client_options)  { default_options }
 
     let(:anonymous_client) { Ably::Realtime::Client.new(client_options) }
@@ -487,7 +487,7 @@ def setup_members_on(presence)
 
       context 'without necessary capabilities to join presence' do
         let(:restricted_client) do
-          Ably::Realtime::Client.new(default_options.merge(api_key: restricted_api_key, log_level: :fatal))
+          Ably::Realtime::Client.new(default_options.merge(key: restricted_api_key, log_level: :fatal))
         end
         let(:restricted_channel)  { restricted_client.channel("cansubscribe:channel") }
         let(:restricted_presence) { restricted_channel.presence }
@@ -688,7 +688,7 @@ def setup_members_on(presence)
 
         context 'without necessary capabilities to enter on behalf of another client' do
           let(:restricted_client) do
-            Ably::Realtime::Client.new(default_options.merge(api_key: restricted_api_key, log_level: :fatal))
+            Ably::Realtime::Client.new(default_options.merge(key: restricted_api_key, log_level: :fatal))
           end
           let(:restricted_channel)  { restricted_client.channel("cansubscribe:channel") }
           let(:restricted_presence) { restricted_channel.presence }

spec/acceptance/realtime/stats_spec.rb

@@ -3,7 +3,7 @@
 describe Ably::Realtime::Client, '#stats', :event_machine do
   vary_by_protocol do
     let(:client) do
-      Ably::Realtime::Client.new(api_key: api_key, environment: environment, protocol: protocol)
+      Ably::Realtime::Client.new(key: api_key, environment: environment, protocol: protocol)
     end
 
     describe 'fetching stats' do

spec/acceptance/realtime/time_spec.rb

@@ -3,7 +3,7 @@
 describe Ably::Realtime::Client, '#time', :event_machine do
   vary_by_protocol do
     let(:client) do
-      Ably::Realtime::Client.new(api_key: api_key, environment: environment, protocol: protocol)
+      Ably::Realtime::Client.new(key: api_key, environment: environment, protocol: protocol)
     end
 
     describe 'fetching the service time' do

spec/acceptance/rest/auth_spec.rb

@@ -23,7 +23,7 @@ def hmac_for(token_request, secret)
 
   vary_by_protocol do
     let(:client) do
-      Ably::Rest::Client.new(api_key: api_key, environment: environment, protocol: protocol)
+      Ably::Rest::Client.new(key: api_key, environment: environment, protocol: protocol)
     end
     let(:auth) { client.auth }
     let(:content_type) do
@@ -596,7 +596,7 @@ def serialize(object, protocol)
       context 'when implicit as a result of using :client id' do
         let(:client_id) { '999' }
         let(:client) do
-          Ably::Rest::Client.new(api_key: api_key, client_id: client_id, environment: environment, protocol: protocol)
+          Ably::Rest::Client.new(key: api_key, client_id: client_id, environment: environment, protocol: protocol)
         end
         let(:token_id) { 'unique-token-id' }
         let(:token_response) do
@@ -649,14 +649,32 @@ def serialize(object, protocol)
       end
     end
 
-    context 'when using an :api_key and basic auth' do
+    context 'when using an :key and basic auth' do
       specify '#using_token_auth? is false' do
         expect(auth).to_not be_using_token_auth
       end
 
+      specify '#key attribute contains the key string' do
+        expect(auth.key).to eql(api_key)
+      end
+
       specify '#using_basic_auth? is true' do
         expect(auth).to be_using_basic_auth
       end
     end
+
+    context 'when using legacy :api_key option and basic auth' do
+      let(:client) do
+        Ably::Rest::Client.new(api_key: api_key, environment: environment, protocol: protocol)
+      end
+
+      specify '#using_token_auth? is false' do
+        expect(auth).to_not be_using_token_auth
+      end
+
+      specify '#key attribute contains the key string' do
+        expect(auth.key).to eql(api_key)
+      end
+    end
   end
 end