What is an SDK?

01 / Understand it · 1 minute

Basic

Think of an SDK as a toolbox: you start with useful parts and instructions instead of making every tool yourself.

SDK vs. API vs. library

API

An interface: the operations software exposes and the rules for using them.

Library

Reusable code your program calls to do a job.

SDK

A kit for a platform or service. It may include libraries, documentation, examples, and build or debugging tools.

An SDK often helps you use an API. The API can still exist without the SDK. AWS explains the distinction ↗

Two common shapes

• Service SDK: Stripe's Node.js library helps a server call Stripe's API.
• Platform SDK: Android's SDK includes tools to build and debug Android apps. SDKs do not always call a web service.

Remember: an SDK saves setup work; you still write the logic that makes your app useful.

02 / Use it · 2 minutes

Intermediate

The usual flow: install the package, create a client, call a method, then handle the result or error.

A real SDK call

This server-side Node.js example reads up to three customers from a Stripe sandbox. Install stripe with npm install stripe, set STRIPE_SECRET_KEY to your sandbox secret key in your environment, save as example.mjs, and run node example.mjs.

import Stripe from 'stripe';

const client = new Stripe(process.env.STRIPE_SECRET_KEY);

try {
  const page = await client.customers.list({ limit: 3 });
  console.log(page.data.map(customer => customer.id));
} catch (error) {
  console.error('Request failed:', error.type);
  process.exitCode = 1;
}

An empty array is normal if your sandbox has no customers. Keep secret keys on the server, outside browser code and Git. Key setup ↗ · Method reference ↗

What the SDK does for you

Your method call becomes an authenticated HTTP request. The SDK formats it and turns the response into objects you can use. You still handle permissions, errors, and pagination (fetching more than one page of results).

Try it: change the limit to 1. Find data and has_more in the response docs and explain what each means.

03 / Ship it reliably · 2 minutes

Pro

An SDK makes requests convenient. Your application still owns what happens when a request fails, repeats, or changes.

Five things to understand

• Timeouts and retries. Check the SDK's defaults. Bound waiting and retry only eligible failures with backoff. Account for SDK retries before adding your own. Stripe configuration ↗
• Idempotency. For supported write operations, reuse one key and the same parameters when retrying the same logical action. A fresh key can create a duplicate; retention rules vary. Stripe's rules ↗
• Versioning. The SDK package version and the service API version are separate. Review migration notes and test both before upgrading.
• Visibility and testing. Record request IDs, timing, and error categories without secrets or personal data. Test timeouts, rate limits, and sandbox behavior as well as success.
• A small boundary. Put vendor calls behind a few functions your app owns. This keeps provider details out of unrelated code and makes testing easier.

SDK or direct HTTP? Use the SDK when its helpers and maintenance save work. Direct HTTP can make sense for a small integration or an unsupported runtime, but you own request formatting, authentication, and error handling.

Think it through: the service completes a write, but the response is lost. How will your app retry without doing the work twice?