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

[dblock]

This is a weird API. So if you specify something invalid it fails silently and returns the whole stats object? That's just bad design - I don't expect an API to succeed and return a different type of object. Shall we have the client raise a specialized exception in this case?

[agrberg]

I didn't either 🤷 I originally wrote the test to raise an error but was surprised when the test failed because the request "succeeded." I'm in favor of straight forward APIs w/ little nuance so an exception would be good here.

[dblock]

Technically in -> with :)

[agrberg]

Rebased and updated ☝️

[dblock]

One last question. This looks good.

[dblock]

Should this be unless result.is_a?(Number) or similar?

[agrberg]

I wasn't able to find an exhaustive list of types IEX currently returns. From experience I know it can return numbers, strings (for strings and dates), and booleans. Testing for one type I know indicates an invalid stat is simpler and more permissive of future changes with IEX's API. 😅 For all I know IEX will return some stat as a tuple encoded as an array and someone would have a bad day debugging because the requested stat is valid.

[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 🎉