Nexmo Java client v2

Big Changes for Nexmo’s Java Client Library

Published March 23, 2017 by Mark Smith

On Thursday, we released version 2 of our Nexmo Java Client library. This new release incorporates a few months of work, and is incompatible with all code written for the 1.x versions of the library. I’ll talk about why we did that in a minute, but first let’s look at some of the new features:

One Client To Rule Them All

We’ve created a single NexmoClient object that can be configured up front and then used to access sub-clients for SMS, Voice, Verify and Insights. This way, if you use more than one Nexmo API, you need to set up the client only once. This provides a single, simple access point to all of the functionality the library offers, hopefully making it faster and easier to get up and running with Nexmo on Java.

Creating a client capable of sending SMS, verifying users with 2FA, and making phone calls is as simple as this:

Full Voice API Support

The most obvious feature of the new library is full support for Nexmo’s Voice API. This allows you to write code that makes and receives phone calls. You can connect people to conference calls, ensure their numbers remain private from each other, read messages, stream audio, and even connect the call to websockets—all without worrying about the underlying REST API—because our client library has you covered.

You can set up a call using a NexmoClient object as follows:

If you like how simple that is, check out some of our quickstart code to see how to get up and running with some of the other features of our Voice API, and take a look at the Nexmo Java Client JavaDoc!

Updated Number Insight Support

We removed the deprecated API and replaced it with the new, better Number Insight API now provided by Nexmo, along with support for all three levels of detail. As before, Basic requests are free (with a small cost per request for Standard and Advanced requests).

Available on Maven Central

For the first time, we’ve released the library onto Maven Central, meaning it can be installed with Gradle using the following snippet:

… or with Maven using the following configuration:

This should make our library much easier to use for our customers using Gradle, Maven or Ivy. If you’re not using a dependency manager, you can download a ZIP file with all our dependencies from our release page.

Why (And How) We Broke Compatibility

We know it causes pain when a library breaks compatibility in a big way. When we committed to bringing the library up to date and to adding our new Voice API, we took a hard look at why the library was difficult to keep current and what we could do to improve the situation. In the end, we decided that making large breaking changes was best done as soon as possible, in one release.

The first thing we did was add a whole load of automated tests, bringing the unit test coverage up to around 85%. This was enough to give us confidence that we could change the code without losing or breaking functionality. Some changes to the code were necessary to make the code testable—you can’t unit test, if you can’t extract a unit. These changes were very helpful in identifying a structure common to all the REST calls, and so we encapsulated this in our new client code and migrated the legacy code to the new framework over time.

What we have now isn’t perfect, but it is a lot simpler and contains less duplication. Apart from moving packages and changing the way you access the individual API client objects, the interfaces haven’t changed a lot for the calls you make to the Nexmo API. If you have any questions about porting, ask them on our community Slack or raise an issue in the nexmo-java repo.

Stats for Geeks

In truth, only half those files were changed, because the majority of them were just moved. The majority of the insertions are unit test code, and code refactored to be more testable and to fit our new architecture.

According to sloccount, a tool for evaluating source lines of code, we have 5215 lines of library code and 4273 lines of test code. I suspect in the future we’ll end up with more lines of test code than library code, but I guess we’ll see. The thing I found really interesting, was the estimate that this amount of code would take two person-years to produce!

What the Future Holds

We don’t plan to make any large breaking changes like this again in the foreseeable future. We still have some small breaking changes planned. We’d like to do some more work around standardized naming, consistent exceptions, and turning some more magic ints into enums. The release of those is a while away. When we do release them – because we’re using semantic versioning – we’ll update the major version number to let you know. In the meantime, we have more endpoints to add, both for Nexmo’s existing APIs and for some of the exciting features being added in the next few months.


In short, Chris (@speaktochris) and I (@judy2k) have done lots of work and really enjoyed working together on this, and we hope you like the result! Check out the library and let us know what you think on Twitter, or by opening GitHub tickets.

Nexmo Logo