Overly Complex SDKs

Good SDKs make writing service code easy. Why do so many of them stop just short of where they should?

Overly Complex SDKs
Photo by Fotis Fotopoulos / Unsplash

I recently had the pleasure of doing some work in Python, integrating with Google's Secrets Manager.  This was a piece of sample code that they provided to show how to use their SDK:

def access_secret_version(secret_id, version_id="latest"):
    client = secretmanager.SecretManagerServiceClient()
    name = f"projects/{PROJECT_ID}/secrets/{secret_id}/versions/{version_id}"
    response = client.access_secret_version(name=name)
    return response.payload.data.decode('UTF-8')

See the problem?  Its exactly the kind of friendly API access method that decent SDKs provide for you.  Sure, if you want to cache the client instead of rebuilding one every time you should be free to do so, but being able to quickly ask the SDK to load or save a secret - with reasonable defaults - would be great as well.

The point of an SDK

The whole reason to write an SDK is to make the caller's life easier.  After all, there's generally nothing that you can write in them that they couldn't write themselves, but its far better doing it in a way that enforces best practicies.

These days, developing by gluing a lot of services together is The Way.  As Sun Microsystems said way back when, "The Network is the Computer".  Becuase we've made it far easier to attach to a variety of external providers, its now far more common that your services are being used casually by someone who'll happily trade a 5% slowdown on intensive usage for a quick, error-resistent use case.

I remember Amazon's libraries being in that same frustrating position of "almost useful", although they may have evolved over the years.  I've created numerous wrapper libraries that do nothing except wrap individual SDK methods with a few default parameters or setup/teardown lines added around each.

Follow StackOverflow

An easy way to make your users very happy is to keep an eye on StackOverflow and other discussion forums.  If you see a lot of confusion over something simple and many people cut-and-pasting a few lines of wrapper code around something you're proividing, add a utility method.  If nobody uses it then there's no harm (almost nobody is worried about a few K in a package, and those who are either hand-code everything or strip out unused methods) and by making your service feel easier to use than your competitors', you may just win a battle you didn't know you were at risk of losing.