The Great SDK Battle: Build vs Buy

In this API-driven era, offering just an API won’t cut it anymore. The APIs need proper documentation, helping code samples, and SDKs to ensure that the end-user quickly gets to the first Hello World. While an SDK is a “make-it-or-break-it” deal for your API, it is just as difficult to get it right. Engineering the SDK is only the first step of this cycle. Once your SDK is published, it needs to be maintained consistently with each bug fix, feature, or new API version.

This blog is the first part of a series on what goes behind SDK creation and maintenance. 

What to Look Out For While Creating SDKs?

From an engineering perspective, each phase of building an SDK is crucial and comes with its own set of challenges. In time-critical situations, you may overlook some issues that can impact your SDK’s usability and maintainability in the long run. Hence, while creating SDKs, you need to address these issues for each API, in each language:

 Step 1: Designing an SDK

• Structure: Need to design SDKs for the user, for future extensibility.
• Language versions: What min/max versions to support? What are the version-specific issues and your upgrade policy?
• Dependencies: This includes fixes, workarounds, limitations, quality, upgrade policy, language support.
• Guidelines: The design, linting, and static analysis guidelines to apply throughout the codebase.

Step 2: Implementing the SDK

• Translate schema to concrete types
• Implementing API calls
• Wrap HTTP implementation in an HTTP layer as HTTP clients come and go, so you may consider a middleware arch
• Handle cancellation of API calls
• Handle API/transient errors and recover gracefully (timeout, retries)
• Handle concurrency via thread-safe calls or chaining
• Handle response caching
• Handle API throttling
• Create interfaces for extension
• Log important events (integrate into system logging)

Step 3: Testing the SDK

• Testing all parts of the SDK code
• Cross-platform/version testing against different language versions, OSes
• Integration tests (end-to-end testing of SDKs)
• Testing your code generator (if you're using one)

Step 4: Writing SDK Reference

• Writing getting started guides
• Writing usage examples for every endpoint
• Creating a reference website for the SDK user
• Creating sample applications (in addition to the code samples per endpoint) to get started quickly

Step 5: Packaging/Publishing the SDKs

• Publishing packages on package repositories
• Recreating bugs reports
• Handling customer issues and feedback related to SDK on GitHub or other forums

The engineering effort required to maintain the SDK program explodes with the number of supported languages, as all the steps mentioned above for creating one SDK will need to be done for each API and each language, every time. Careful planning can reduce some of this cost, but the perpetual maintenance cost will still exist.

Why Do SDKs Need Maintenance?

Once you’ve successfully implemented and published your SDK, the endless cycle of maintenance begins. Maintenance is required from an engineering as well as a business perspective, hence making the cost of maintenance much higher than the development cost, as again, this applies to the SDKs of each language per API.

Maintenance From Engineering Perspective

If you think creating an SDK is enough, updating it is much more resource and time-intensive. Technology and APIs are continuously evolving, and SDKs need to keep up with them. You will need to update your SDKs (on time!) for the following reasons:

1. Updates to the API: With every update to the API, the SDKs need to be updated for all languages simultaneously or the SDKs will lag behind the API updates.
2. New language or framework versions: This occurs more often than you realize and is a major operational burden.
3. Language ecosystem evolution: New IDEs, new build tools, major fragmentation in the ecosystem requires constant maintenance.
4. New dependency versions: This results in more fixes, updates, security fixes, development of supported features.
5. Bug fixes in the SDK: You need to test and fix bugs continuously to ensure no blockers occur at the user’s end, negatively impacting your API’s experience.

Maintenance From Business POV

Apart from the high maintenance required by your SDKs to tackle engineering concerns, you also need to consider business-oriented issues that may affect your SDK delivery and performance:  

1. Lock-in on internal SDK team: A custom internal tool or process that requires maintenance and a lot of engineering time/resources.
2. Speed of update: SDKs and documentation lagging behind API releases unless you write a general-purpose code generator.
3. Opportunity cost: Can other areas in your API program use this engineering time?
4. Time-to-market: If you're just starting with building SDKs, when will they be available and what do you do in the meantime?
5. Operational burden: Reduces developer velocity and happiness over time due to fighting fires, adds project risk to API program, increases costs for the organization.
6. Operational excellence: Can you achieve the same level of quality and attention to detail compared to a company that exists only for creating SDKs?
7. Keeping the SDK program running: Maintaining SDKs takes time and energy. Building it isn’t where most of the expense lies. Instead, that comes with running and maintaining complicated processes and tools behind the SDK program.

According to bls.gov, the median salaries in 2020 were as follows:

• Developer: $110,140 per year
• Tester: $110,140 per year
• Technical Writer: $74,650 per

To make things simple, let’s assume that building a single SDK for 1 API in just one language (including research, documentation, and testing) takes 4 weeks to build. This makes the upfront cost around $22,687. Now add in the maintenance time to 2-3 days per month, and SDK maintenance can go up to $29,089, bringing the total to $51,776. Hence, building and maintaining a single SDK in a fairytale situation, without any hiccups, can cost around $52,000.

Now imagine if you're building SDKs for 8 languages for 10 APIs, this will skyrocket this figure to almost $4M. 

APIMatic as a Code Generator

You can choose to address all of the aforementioned issues yourself and write the SDK code by hand, or even try to solve your problems using an in-house code generator, but the process itself is quite hard and can take up to years to streamline. Not to forget the time and resource overhead involved. However, APIMatic can handle these issues automatically at the back-end for you, while you focus on building new solutions. APIMatic’s flagship code generator creates SDKs for multiple languages, including:

• PHP 
• Ruby
• Python
• C# (.NET)
• Java
• Typescript (coming soon)

These SDKs are featured packed with thread-safe configurations, retries, logging, and more. The SDKs accurately map your API definition files into helper classes, model classes, exception classes, and controllers. APIMatic also creates comprehensive, language-specific guides with the SDKs that contain tailored tutorials based on your language and popular IDEs to help users easily get started with the SDK in their applications. For more detail, read here on APIMatic SDKs.

APIMatic creates SDKs from OpenAPI 2.0 and 3.0, API Blueprint, RAML as well as several other popular API specification formats.

Reduce Time to Market

Internal SDK programs can become costly to maintain over time due to churn (new API versions, language features, and library versions or API program engineering turnover). If you are forking open-source code generators, it means you will be maintaining all the custom templates and syncing your project with the upstream for fixes/bugs perpetually. Also, there is no customer support.

APIMatic significantly cuts down on costs and time for creating and maintaining SDKs in any language. You only bring in your API specification file and roll out your updated SDKs in minutes, rather than weeks, months, or years. 

Automate SDK Generation and Maintenance

APIMatic offers programmatic access to their flagship Code Generator, which allows integrating the autogeneration of SDKs directly into your CI/CD pipelines. So every time the API is updated, the corresponding updated SDKs are automatically generated, without any manual interference. Learn more about how APIMatic offers CodeGen-as-a-Service.

Ensure Robustness with Battle-Tested SDKs

SDKs generated by APIMatic are already deployed by large companies and installed several million times, meaning that the SDKs are reviewed by a larger user base that helps us design better SDKs.

To Sum It Up

Creating SDKs in multiple languages is quite resource-intensive and expensive. Apart from just development, a major chunk of time and resources is spent on maintaining the SDKs, both from an engineering and business point of view, for all languages for each API. APIMatic is a developer experience platform that takes care of all the SDK generation and maintenance work behind the scenes while your developers can focus on their applications and innovative solutions. See firsthand how APIMatic can help enhance your developer experience.