Beautiful SDK Design in Java for APIs

By Micah Silverman

Elevator Pitch

Often times Java SDKs for APIs look more like the API they represent than idiomatic Java.

This talk examines how great SDKs are built using design patterns.

It covers: enforced separation of Java api and implementation, use of generics, a caching layer and hiding network traffic.


The (now defunct) Stormpath SDK had a great design approach from its original author, Les Hazlewood.

It has an enforced separation of api and implementation. It does this by using the api module as a compile time dependency and the implementation module as a runtime dependency.

It has a DataStore interface that makes heavy use of generics to support CRUD operations for all objects represented in the API. The implementation hides the actual network traffic and includes rich support for retry with backoff and error handling. Developers only ever have to deal with the DataStore, POJOs and method calls to “interact” with the API.

It also has a rich, interface-based caching layer. The default implementation is robust and suitable for single-JVM environments. It’s easy to drop in a distributed caching layer, such as Redis or Hazelcast.

All of this combined makes this one of the best designed SDKs in Java. In this talk, all these secrets are revealed against a completely different API: DigitalOcean’s Droplet API. There’s a few slides and lots of code, including some live-coding.