Add support to fetch a single key stat

[agrberg]

Alternatives I considered:

Keep the method signature the same and supplying the stat in the options hash

def key_stats(symbol, options = {})
  stat = options.delete(:stat)
  params = { token: publishable_token }.merge(options)
  url = "stock/#{symbol}/stats"
  return get("#{url}/#{stat}", params) if stat

  IEX::Resources::KeyStats.new(get(url, params))
  …

Wrap the single stat in a IEX::Resources::KeyStats instance

def key_stats(symbol, stat = nil, options = {})
  params = { token: publishable_token }.merge(options)
  url = "stock/#{symbol}/stats"
  data = if stat
           { stat => get("#{url}/#{stat}", params) }
         else
           get(url, params)
         end

  IEX::Resources::KeyStats.new(data)

This would keep the return type the same and with nil being provided for any of the other stats. E.g.:

single_stat = client.key_stats('VTI', 'dividendYield')
single_stat.dividend_yield # 0.01271760965303361
single_stat.pe_ratio # nil

Let me know what you think!

[dblock]

I definitely prefer the former because the latter is an API change, and we should only do this very carefully. Options is exactly designed for those ... optional options :)

Next, the result of this is a single value? Should we just add a key_stat method instead of having this one return two different types?

[agrberg]

🤔 that's a great question. There's no reason that because IEX's API groups a single stat as a special case of all basic stats that the client need to do the same.

I think having a key_stat endpoint solves all of the issues:

• There is no API breaking change for a now mandatory stat client.key_stat(symbol, stat, options)
• The return type of the existing method doesn't change and it's expected that key_stat returns the data in the type of the choosen the stat.
• Simpler to read logic

[agrberg]

Rebased and updated ☝️

[dblock]

Merged. Thanks!

[agrberg]

happy to give back 💪

[dblock]

Maybe time to cut a release?

[agrberg]

Good idea. Just launched v 1.5.0 w/ the new endpoint 🎉