The Nexmo Ruby SDK recently published a major version release, v7.0.0. This new version introduced improved support for API error handling, renamed an existing class name to match the rest of the Nexmo SDKs, and added more static typing.

API Error Handling

The most significant change in this new release is the way the SDK handles errors from our earliest legacy APIs. There are some Nexmo APIs, like the SMS API for example, that will return a 200 OK HTTP status along with an error code to report that something went wrong.

Previously, the SDK treated all API responses that returned a 200 OK as a success and passed along to the user the body of the response. As a result, developers needed to create conditional checks in their code for an error code within the 200 OK response to know if there was something wrong. A classic example of how this was previously done with the Ruby SDK is the following:

response = client.sms.send(
  from: 'Acme Inc',
  to: TO_NUMBER,
  text: 'A text message sent using the Nexmo SMS API'
)

if response['messages'].first['status'] == 0
  puts 'Success'
else
  puts "Error Code #{response['messages'].first['status']}: #{response['messages'].first['error-text']}"
end

Now, the SDK will check for non-zero status codes for you and raise an exception automatically in your code if the status code is non-zero. This removes the need for you to create conditional checks like the one above inside your application. Instead, a more condensed version now works:

response = client.sms.send(
  from: 'Acme Inc',
  to: TO_NUMBER,
  text: 'A text message sent using the Nexmo SMS API'
)

If there is an issue, the SDK will raise an exception and report the error-text and status from the API to you. That information can be used to lookup more details in the API Reference. For example, each corresponding error code within the SMS API can be found inside the API Reference with more detail behind its meaning.

Class Naming

The Nexmo SDK team has been busy making sure that all of our SDKs conform to our Server Library Specification. We recently revamped the specification-you can read about that work in a post by the Server SDK initiative lead, Chris Tankersley, on the Nexmo blog.

As part of the Ruby SDK audit, we discovered that one of our classes had a name that was distinct from the rest of our SDKs. We know that many developers do not only work in one language, and it is important to us that the experience of using our SDKs remains as consistent as possible across languages. When there are differences they should be a result of particularities in each language, and idiosyncratic distinctions should be minimized.

Therefore, we have renamed the Calls class to Voice. This is a a breaking change, so please be mindful of it when you choose to upgrade to the v7.0.0 release.

Static Typing

We introduced static typing into the Ruby SDK in the version 6.3.0 release. You can read about our rationale for doing so in the release blog post and follow along with some of the early adoption journey in our YouTube series.

We set on a path of gradually introducing more method signatures in each new release. In this release, we have introduced static type checking to the Account and Alerts classes. They join the previously type-checked SMS class in our growing list of statically typed classes.

What's Next?

We have more exciting development for the Ruby SDK in the pipeline. They include adding the Conversations, Messages and Dispatch APIs once they move out of beta and into general availability.

The SDK codebase is publicly available on GitHub, and we welcome contributions and involvement. Join us in the conversation on GitHub or connect with us on the Nexmo Community Slack.