Most engineers rely on software development kits, or SDKs, in their day-to-day work. Many in our industry would recognize SDKs as a set of tools wrapping an existing application interface, often in the form of a software library. We use them for everything: from simple utility libraries, to vital encryption and security technologies, to towering and complex virtual reality frameworks; SDKs provide a sanitised, safe, interface to get work done quickly.

But how much do we know about the SDKs we use? Why did the designer build an SDK in a particular way? Could it have been done differently?

In this series of blog posts, we’ll dissect the Braintree v.zero SDK and find out what lies beneath its skin. v.zero is made up of two SDKs. The first is a Javascript SDK, used on the client, enabling capture of a user’s payment details (credit card, PayPal etc). The second is the server side SDK. This handles communication between your application and the Braintree gateway. This server side SDK, powering requests to Braintree, will be the focus of this blog, so grab your gloves and mask, and get ready to be elbow deep in the details -- and grasping wisdom from our autopsy.

Nurse, pass me my scalpel.

Let's begin!

The neck bone’s connected to the hip bone...wait, what?

Robert Martin, aka Uncle Bob, a beloved software engineer known for his contributions to the Agile Manifesto, once said that the top-level structure of a project, the architecture, should scream out the use case. This is as true for SDKs as it is for the skeleton of an animal; it’s pretty obvious just from the size of the bones if we’re looking at a mouse or an elephant. From the top-level file structure (our SDK’s skeleton) the nature of our subject is visible. The bones of our file structure are connected by joints (the dependencies and class hierarchies) and set in motion by muscles and ligaments (the functions). Here we’ll explore the bones and the joints, identifying dependencies between files.

Our first observation is that some files share a common suffix. For example, “braintree_gateway” exists in the same directory as a file called, simply, “gateway.” Being the clever investigatory surgeons we are, we deduce that these things must be related.

Knee jerk reaction

To test this theory, let’s dive into the file “credit_card_gateway,” we do indeed see that this file exports a class that extends from “gateway”. Fantastic! We’ve begun to identify dependencies amongst our components. The joints are falling into place. But with so many files and so much complexity we need a strategy that will allow us to make sense of this before rigor mortis sets in. We’re best off identifying the very basic body parts, and using these to map out the full anatomical structure.

Fortunately, the very nature of SDKs guides us. For example, the Android SDK exposes an interface through which we can use a device’s hardware. In the same vein, our Braintree SDK facilitates communication with the Braintree servers in order to process payments. It is a wrapper around a web API, with a sensible interface and added utility functions.

A web API obviously depends on the ability to communicate with HTTP. These HTTP requests will be vital in this SDK, shuttling signals between our application and the web, acting as the central nervous system of the body. Woven into the bones lying upon the operating table, the “http” file waits for us to explore it.

Cleaning up

We’ve now completed Stage 1 of our autopsy. In my next post we will embark on Stage 2, dissecting “http”, getting a closer look at how our applications communicate with Braintree. We’ll see how information makes its way into and out of the SDK and any apps built upon it.