Code

Creating a Successful SDK

Sebastian Arrubia on April 14, 2016

The new era of software faces a new major challenge: Distribution. As we are thinking about creating applications to run on different third party services or devices like smartphones, watches, TVs, notebooks, tablets, even “things” - Engineers and architects are searching for ways to develop for distribution while continuing to move quickly.

This means that each time that we talk about “How should we design our apps architecture?” or “What is the best option to integrate with third party services?” we need to start considering APIs and SDKs. It’s easy to find information about “distributed architectures” and "API implementations", but for an SDK the explanation stops at “Software Development Kit”. 

But really, what is an SDK?

Commonly, SDKs are referred to as a set of libraries to be downloaded and used for integrating our systems with others via APIs, for instance the Facebook SDK or the AWS SDK. Essentially, an SDK is a complement to an API that abstracts the complex business logic and makes development work easier. However, an SDK could also be more than this. In some cases, the SDK could require processes to run in the background or even in parallel with applications like services. The SDK could also have a strong dependency on another service: a database, a cache, etc. 

In these scenarios, we should take a moment to consider SDK architecture and first answer some questions:

What about the audience?
What about the SDK performance?
What about the SDK security?
What about the scalability?
What about the concurrency on distributed scenarios?
What about the SDK error management?
What about the technologies in which we need to implement the SDK?
What about the integration between SDK and your servers?

These initial questions are key to creating a successful SDK. So, let's go answer some questions!

Audience: An SDK is created by developers for developers, so keep a clear and accurate technical documentation, code and tests.

Performance: The SDK is embedded into other applications that have specific performance requirements. Due to this, the SDK must not be a bottleneck so ensure that your SDK performance is as efficient as possible. Microbenchmarks and profilers are great tools for this job.

Security: Some SDKs need a security mechanism to validate the user’s or application’s authenticity. Others have to implement Cryptographic algorithms to guarantee data consistency and security. So, what is your security requirement?

Scalability: Is the SDK flexible enough to let the applications scale without issue? This is a important to consider if your SDK is something more than a code library. For instance, if the SDK needs to run custom processes, has a strong dependence with a cache system or a database, or even shared resources (just like memory). Well defined contracts with your components will live a long time.

Concurrency: If the SDK has some dependency with a shared resource or works with external services, consider the level of concurrency in order to avoid issues like “race conditions” and bottlenecks result of lock contention in your code..

Errors: One of the most important requirements of an SDK is error management. It’s very important to make a decision about error management early and document it thoroughly. Some SDKs prevent exceptions and track errors using a log system. This approach avoids critical errors on main applications, but makes it difficult to identify if something goes wrong as the behavior could look normal. 

Some SDKs throw exceptions, and this is critical, because if exceptions aren’t captured by developers the main application could fail significantly.

Technologies: The SDK should be capable of implementing with different technologies.  However this particular requirement gets complicated quickly if the details of each technology are not considered upfront. For example:

  • Supported data types: strings, numbers, lists?
  • Language platform: 32bits or 64bits?
  • Concurrency: it is supported by the technology?

If you find differences across technologies, try to wrap these in custom libraries or think about the best approach for each separately.

Integration: If connecting the SDK with an external service, we should also think about the integration. Typically, integrations are setup via an API but there are other details to consider. Can we support the API connection? Is it a standard API, like RESTful or SOAP?  Do we have an API contract? What about the API security?

Overall, SDKs are great tools to simplify the way your customers and teams interact with your product, which removes the complexity of interacting with APIs and abstract them from implementation details. Just don’t forget to ask yourself the important questions upfront to ensure your SDK is as successful as possible.

We're Hiring!

Join the Team