How SDKs Benefit API Developer Experience

How SDKs Benefit API Developer Experience

Posted in

Since the dawn of modern web APIs, there have been Software Developer Kits (SDKs). SDKs help transport complex API mechanics into languages and platforms that developers are familiar with. And their importance to the developer experience seems to outlast the constant evolution in the tech industry, even the latest generative AI craze.

“I see SDKs as a key ingredient in the developer experience,” said Sidney Maestre, VP of Developer Relations, APIMatic. “It’s one of the things I look for when exploring a new API. Do they have any client libraries or SDKs written in a programming language I know?”


Attend the Platform Summit 2023 to catch Sidney Maestre’s session.

Ahead of the Platform Summit 2023, we are interviewing some key speakers to explore their upcoming talks and get their perspectives on the state of the API economy at large.

Sidney Maestre, one such Platform Summit speaker, has had an illustrious career working closely with API initiatives from Xero to Lob. Now at APIMatic, he helps companies automate how they build developer experiences and drive the adoption of their APIs through SDKs, interactive documentation, guides, and code samples.

Below, we’ll reprint some thoughts from Maestre on the importance of SDKs for developer experience, a theme of his upcoming session.

How do SDKs benefit the API developer experience?

We all want a happy path to start exploring an API, and I think SDKs offer the best experience. With code libraries in my language, along with a getting started guide or starter applications, I spend less time configuring my project and figuring out authentication and dependencies. If I encounter any issues, the API support team can easily replicate my problem since we share a common codebase.

Beyond “Hello World,” I want to understand how an API can address the business needs of my application. Having use case guides or recipes that include code samples showing me how to solve a problem using the SDK is super helpful. Also, having runnable code samples as part of the API reference opens the door for self-directed experimentation.

From the IDE perspective, I avoid jumping back to the docs and can achieve a state of flow by using type hinting, code completion, and inline documentation available through the SDK code library.

What is the overall state of the API economy, and why is DX so important?

We’ve come a long way over the past 10 or 15 years. There has been incredible growth in the number of APIs available to developers. This is a blessing and a curse, as we don’t always have time to evaluate all the API options.

Therefore, it’s important to make a good first impression. Developers will be looking for signals that your API is worth considering. Make it easy to onboard, communicate the use cases you solve, offer clear pricing options, and speak the language of your target audience. This means SDKs and code samples in their preferred programming language.

Developers are key stakeholders in the purchasing decision, and leaders take their recommendations seriously. With more APIs competing in the same space (just look at payment APIs), a good developer experience is a competitive advantage.

Are SDKs still relevant? Why do we need them?

At APIMatic, we looked at 100 API companies, and 94% offered official SDKs to their developer community. They were either handwritten, built with code generators, or some combination of the two. That’s a pretty good proof point that SDKs are still relevant.

SDKs are a big investment, and I don’t think API providers would continue to offer SDKs if they weren’t seeing downloads, positive developer feedback, and other benefits like a reduction in support tickets and faster onboarding and integration times.

Why do developers need them? Of course, not every developer wants to use an SDK. Some have their own set of libraries and build API integrations often. But, the vast majority of developers appreciate the convenience of a purpose-built library. SDKs give developers an interface designed for interacting with your API in their preferred programming language. This interface hides the API call implementation details so developers can focus on building their application instead of reading your API reference docs.

At the end of the day, SDKs save developers from writing a lot of boilerplate code to perform common tasks. They offer a foundation to manage authentication, data validation, serialization, error handling, and transient errors like network delays.

What are some best practices API providers should consider as they build out their SDKs? What are some common elements every SDK should have?

A good way for API providers to start is by understanding that SDKs are not a weekend project but an ongoing investment in their developer experience. SDKs are not static artifacts but must continuously be updated to keep parity with their API, address security concerns, and incorporate developer feedback.

Developers want many things from their SDKs, so I’ll focus on a few best practices…

Developers want SDK code libraries that are easy to discover, install, configure, and use. Each client library should be accompanied by SDK-specific documentation, like a getting started guide for using the code library. SDK code libraries and examples must be idiomatic (following the style and coding preference of each language). The last thing a Python developer wants is code examples written in the style of a Java developer.

Developers want SDKs that are kept up-to-date and support all available endpoints and operations. Beyond API parity, developers like to see regular releases that address bug fixes, improvements, and vulnerability patches. Regular updates increase confidence that SDKs are well maintained, and by including test coverage, developers can confirm the quality of the client libraries.

Lastly, developers seek robust SDKs that handle transient errors like network failures through configurable timeouts and retries. Be sure to provide types (classes, structs, interfaces, or enums) in the languages that support them. This helps developers create the correct requests and handle responses through type-hinting and compile-time checks. Define how the SDK will handle API errors, catch exceptions and surface them with useful messaging.

Of course, provide support for developers with SDK-related queries and issues via your help desk or GitHub issues. This community engagement allows API providers to share their SDK roadmap, which builds trust in your technology.

What are some examples of stellar SDKs on the market?

Of course, API leaders like Square and Stripe deliver great SDKs, and you see them prominently featured in their developer experience. If you look at their developer portals, you’ll see SDKs are in their quick start guides, API reference docs, and use-case guides.

Launch Darkly has gone deep with its SDK program. Last time I looked, they had 27 SDKs built for client-side, server-side, and edge environments. They offer a lot of functionality which is unique to their feature flag product like offline caching of rules. I spoke with Brian Rinaldi who works at Launch Darkly as a developer experience engineer and he shared that they discourage users from using their API directly and prefer they utilize an official SDK. As he said, developers could build their own client libraries, but why would you want to do that?

Regarding the Platform Summit, why are you excited to participate/speak?

Speaking at Nordic APIs previously was a blast. The speakers and content were top-notch, and I expect the same this year. I’ve been missing in-person events and look forward to reconnecting with old friends and meeting new ones.

Without giving away too much from your talk, what can attendees expect?

The title of my talk is “You Don’t Need SDKs, Wait Maybe You Do?“. As API programs mature, they ask, “Does it make sense to invest in official SDKs?”. I want to unpack that question and discuss factors to consider before embarking on this journey. I’ll share my experience working for a company where the ROI of SDKs was not there and another company that went from a few poorly supported API wrappers to 6 automated SDKs built using OpenAPI definitions. I’ll also share best practices around building an SDK program when you are ready.