How SUMO Heavy is helping modernize SDKs and documentation for a frontrunner in cryptocurrency payment systems.
BitPay is a payment service provider for cryptocurrency that enables the acceptance of cryptocurrency payments on websites and applications.
Their history so far is impressive:
BitPay approached SUMO Heavy in 2022 to perform a Weigh-In for their SDKs, during which we performed a full analysis of these SDKs and recommended a structured path forward to create a more engaging developer ecosystem.
An SDK, or software development kit, is a collection of software development tools provided by hardware and software vendors that developers can use to create applications. The BitPay SDKs were always available on GitHub, but we noticed they were missing a few key components:
These created a starting point for us to jump in and begin updating the client SDKs. We first started with automated testing for the Java and PHP clients, which would set the stage for introducing stability. This also exposed a few long-standing bugs that are now covered by the unit and integration tests.
Next, we introduced CI pipelines to run the tests on all commits for all forks, as well as in pull requests. This allowed us to move on to the next step: language and platform best practices.
Generally, languages will have guidelines to follow to make your code consistent, testable, and familiar. An excellent example of this is PSR-12 for PHP. In this case, the pipeline will run PHP CodeSniffer to ensure the code is consistent across the entire SDK. This will make it easier for contributors to know how to write their code.
After implementing automated tests, we started to move into documentation, which we'll discuss more in-depth in this case study.
The last two pieces are important. Formalized version support ensures that we encourage implementers of the SDKs to keep up with the support schedule of their language and framework. For example, technologies older than Java 8, Node.js 14.x, PHP 8.0 are not supported because their official versions aren't. This also helps BitPay avoid becoming stuck supporting unsupported language versions, which may have vulnerabilities or will inevitably become more challenging to manage with time.
Finally, prior to the new SDK versions being tested, there were two versions for most languages. The "lite" SDKs are simple to implement but only support the pos facade. This API facade is limited in functionality and mostly focuses on invoice creation. It does not require signed requests, so it has much less complexity. There are also "full" SDKs, which support the entire API but are more challenging to implement because they require request signing. This is done for you by the SDK, but it does require the creation of a private key.
Managing two separate versions of the SDKs is daunting because it also means supporting multiple versions of the tests, documentation, and code. The answer was to build one SDK for each language that supports all API facades and allows for both signed and unsigned requests. This allows implementers to start with a simpler facade and add complexity as needed, without changing the SDK. The changes needed to move from the POS facade to those requiring signed requests are low-effort with this new method.
It's important to note that this is a journey. These projects are still in progress, with more updates coming. Look out for the next releases of each SDK. The Java and PHP unified SDKs are already in beta, with Node.js coming next.
As part of our day-to-day, we work on improving the technical documentation (docblocks) for the SDKs so that technical documentation is easily generated. This process leans into JavaDoc, PHPdoc, and other annotated docblock standards. This allows us to generate documentation about classes, properties, and other aspects of the code to help implementers and their IDEs to understand better how the various objects and methods work.
We were also tasked with moving the consumer-facing documentation. Initially, it was integrated as part of the BitPay website using a static site generator. This wasn't inherently problematic, but it relies on access to the private codebase. Since BitPay works in the payments industry, they have restrictions in place for who can access the private code and this created many levels of permission to go through to update the documentation.
To make the documentation more accessible to the SDK team, we have moved the official documentation to Readme.io at https://bitpay.readme.io/docs. This documentation includes guides for getting set up and what to expect, API documentation for those who want to work directly with the APIs, and each SDK. It also allows us to push a changelog RSS feed with announcements.
We can now assist BitPay with client services with the more robust SDKs. Our goal is to continuously improve the SDKs and the development ecosystem. We are working hard on ensuring there's a feedback loop available to all SDK implementers and those who are interested. We're doing this in a few ways:
We're honored to be a part of the path of direct interaction. We are active in BitPay's client interactions, helping with onboarding and providing developer support. This includes creating small demos for clients in their preferred stack, leading to a new "Kiosk demos" initiative that uses the new unified SDK betas.
At a high level, we are helping them create a developer ecosystem while directly supporting new and existing clients.
If you’d like to learn more about SUMO Heavy, drop us a line, give us a call or contact us on social media.