Why an SDK is Critical to your API Offering

While you need to give direct access to your APIs, an SDK is a critical piece of your offering.

There was an article on the ProgrammableWeb on Sending.io NOT offering an SDK for their service. I think in most cases, this approach is wrong.

Sending.io decided to offer only an API layer for its customers. You can access their REST APIs, but how you do it is your problem – even when what they give is designed and built for mobile devices.

API and SDK

I’ll start with a quick explanation of the two – at least in the scope of this post. There will be those who will definitely object my definitions here, but the idea is just to make the distinction I need here – and not to pontificate the meaning of the two.

• API – an API is a set of operations you can use to access a backend service of sorts. Assumption is this is a server-side API, where we have a service on some remote server (probably on AWS or whatever other cloud), and that service offers access to it via APIs. You invoke the API by making a remote call from your machine or device to the cloud running the service. Usually these APIs will be REST based, though not always
• SDK – an SDK is a piece of code that gets embedded into the customer’s service. The customer is a developer who decided to use your API, so he downloads your SDK and puts it in his own code. The SDK itself calls the API when necessary to get things done. The result – the customer calls the SDK locally, the SDK calls the API remotely and your service gets used

Why not an SDK?

Back to Sending.io and their reasons – from this article:

• SDKs introduce performance issues
• Reduces control of the customer using it
• Crashing SDKs
• Privacy issues

While this may work in the gaming industry, I think it is not workable in many other industries. Here are my thoughts on this one:

It all boils down to your execution

There are two ways to treat an SDK – as part of your offering or as an afterthought.

If you treat it as an afterthought, then performance issues, crashes and privacy issues will crop more frequently than not.

With most SDKs today built as frontends to a backend REST API, it makes perfect sense that some of them just aren’t written well: Backend developers are good at scaling a service to run in the cloud. For them, considerations of memory and performance of the single session in the same way that a native Android developer thinks about is foreign.

If you really want to offer an SDK, have a pro build it for you.

See also the article on Video Call API.

The customer’s control

Assuming what you have on offer is a closed binary SDK that the customer ends up using, then control may be an issue.

It doesn’t have to be this way.

There are 3 options you can take here, each with its own control points for customers:

1. Offer your SDK as a closed binary, but also give access to the backend API
   • Those who wish to use the SDK to shorten their time to market can do that
   • Those that wish to have more control can use the API directly
2. Offer your SDK in source code format
   • This gives more control to your customer, who can now debug the code
   • The customer may modify the code, and in such cases, you should make it clear your support will be of the backend API only
3. Offer a sample SDK client only
   • Provide a reference written in the native language of choice
   • Don’t offer support for it, but write it in a way that makes it easy to understand and modify

Why an SDK is needed?

There are several reasons that make an SDK so powerful:

1. While REST APIs are simple enough, connecting to them can be quite a hassle
   • Which native library should be used? Have the APIs been tested with these libraries? Having this one decided, implemented and tested makes life easier for customers
   • What authentication mechanism is provided? How do you implement it on your own in the native language? This can eat up many hours, so having that done for customers reduces the friction and the chance of your customer moving to a competitor
   • There’s a flow issue – you need to call API A then API B then check something locally before running API C. Developers never read documentation. Give them a sample to work from in the SDK, and half your problems are solved
2. It might not be REST…
   • There’s a shift towards WebSocket communications in some places. Documenting the spec and having customers follow it isn’t easy
   • Give an SDK instead, and the actual protocol you use for the WebSocket becomes irrelevant to the customer – AND allow you to easily update it in the future
3. You might want to run things in the client side
   • WebRTC, for example, runs on the client side
   • You can’t really offer a backend API and just forget about the client side – there’s a lot of code that ends up there
   • That code has value – especially on mobile

Plan on offering a backend API for your customers?

You shouldn’t just ignore an SDK – especially not if you plan on having developers integrate with your APIs inside mobile apps.