SDK

Also known as: Software development kit

On this page 8

An SDK (software development kit) is a packaged collection of libraries, tools, documentation and sample code that lets developers build software for a specific platform, operating system, service or hardware device. In the context of APIs, an SDK usually wraps a remote interface, such as a REST API or gRPC service, in idiomatic, language-specific code so that developers call ordinary functions instead of composing raw HTTP requests by hand.

SDKs are a core part of programming practice because they shorten integration time, reduce errors in authentication and serialization, and encode the provider’s recommended usage. They also introduce a dependency that must be versioned, updated and secured like any other third-party code.

What an SDK contains

An SDK bundles everything a developer needs to target one platform in a single installable package. The exact contents vary, but a mature SDK combines runtime code with build-time tools and learning material, so that a new developer can move from installation to a working call in minutes.

The table below lists the typical components and the role each plays in development.

ComponentPurposeExample form
Client librariesWrap API calls in native functions and typesPackage for npm, PyPI or Maven
Authentication helpersHandle keys, tokens and request signingCredential providers, OAuth flows
Data modelsMap API payloads to typed objectsGenerated classes or structs
Command-line toolsAutomate setup, deployment or testingCLI for login and configuration
Emulators and simulatorsRun the platform locallyDevice simulator, local service mock
Documentation and samplesTeach correct usageReference docs, quick-start projects
Debugging and profiling toolsDiagnose behavior and performanceLog viewers, tracing utilities
Typical components of an SDK

Platform SDKs, such as those for mobile operating systems or game consoles, also ship compilers, headers and system images, whereas API SDKs are usually lighter and consist mostly of client libraries.

How an API SDK works

An API SDK sits between application code and the network and translates method calls into protocol messages. When a developer calls a method such as client.orders.create(...), the SDK validates arguments, serializes them to JSON or Protocol Buffers, attaches credentials, sends the request to the correct API endpoint, and converts the response or error back into native objects.

Good SDKs also implement cross-cutting behavior that every integrator would otherwise rebuild: automatic retries with exponential backoff, respect for API rate limiting headers, transparent API pagination through iterators, request timeouts, idempotency keys and structured error types. This hidden work is often the main reason teams choose an SDK over hand-written HTTP calls.

Many providers now produce SDKs through code generation from an OpenAPI or Protocol Buffers definition, then add hand-written layers for ergonomics. Generation keeps several language SDKs consistent with the specification, while handcrafted code improves naming, documentation and edge-case handling.

An API is a contract, while an SDK is an implementation that helps developers use that contract. The two are often confused, together with libraries and frameworks, so the distinctions below are worth stating precisely.

ConceptWhat it isRelationship to an SDK
APIDefined interface for interacting with a systemAn SDK typically wraps one or more APIs
LibraryReusable code for a specific taskAn SDK usually contains several libraries
FrameworkStructure that calls developer codeAn SDK may include a framework, but not always
API clientCode that sends requests to one APIThe core runtime part of an API SDK
CLICommand-line interface for a serviceOften shipped as part of an SDK
ToolchainCompilers, linkers and build toolsIncluded in platform SDKs, rare in API SDKs
How an SDK differs from related concepts

A useful rule of thumb: an API can exist without an SDK, but an API SDK cannot exist without an API. Every operation available through the SDK must ultimately map to an operation the API exposes.

Types of SDKs

SDKs are classified by the target they support and by the language they serve. The category determines size, installation method and update cadence.

SDK typeTargetTypical use
Platform SDKOperating system or deviceBuilding native mobile or desktop apps
Cloud service SDKCloud provider APIsManaging storage, compute and queues
Third-party API SDKA single web servicePayments, messaging, maps or analytics
Hardware SDKSensors, cameras or embedded boardsReading device data and controlling firmware
Embedded analytics or ads SDKInstrumentation inside an appCollecting usage events or serving ads
Common SDK types and when they apply

Embedded SDKs deserve particular attention because they run inside the host application with its permissions. A tracking or advertising SDK can collect data the app owner never intended to share, which makes it a frequent topic in privacy reviews under regulations such as the GDPR.

Choosing and maintaining an SDK

Adopting an SDK is a dependency decision, not only a convenience decision. The decision table below summarizes when an official SDK is the right choice and when direct API calls are preferable.

SituationRecommended choiceReason
Complex authentication or request signingOfficial SDKSigning logic is easy to get wrong
Only one or two simple callsDirect HTTP callsAvoids a large dependency
Language without an official SDKGenerated client from OpenAPIKeeps types aligned with the spec
Strict bundle size limitsModular SDK or direct callsMonolithic SDKs inflate binaries
Long-term production integrationOfficial SDK with pinned versionRetries and errors are maintained upstream
When to use an SDK or call the API directly

Once adopted, an SDK needs active maintenance. Teams should pin versions with a lockfile, read changelogs before upgrading, follow semantic versioning signals for breaking changes, and track deprecation notices tied to API versioning. Neglected SDKs eventually call retired endpoints or miss security fixes.

Limitations and risks of SDKs

SDKs trade control for convenience, and that trade carries specific risks that experienced teams evaluate before committing.

  • Supply-chain exposure: a compromised package or transitive dependency runs with full application privileges.
  • Lagging feature coverage: new API features often appear in the SDK weeks or months later.
  • Leaky abstractions: hidden retries or caching can cause duplicate operations if idempotency is ignored.
  • Version conflicts: two SDKs may require incompatible versions of the same HTTP or JSON library.
  • Vendor lock-in: code written against proprietary types is harder to migrate to another provider.
  • Binary size and startup cost: large SDKs slow mobile apps and serverless cold starts.

The most reliable mitigation is to wrap the SDK behind a thin internal interface, so that application code depends on the team’s own abstraction and the SDK can be upgraded or replaced in one place.

A non-technical view

Imagine buying flat-pack furniture. The pieces alone are not enough; the box also includes screws, a small tool and an instruction booklet. An SDK is that complete box for software builders. It gives them ready-made parts, the right tools and clear instructions for working with one product or service.

Without an SDK, a developer can still connect to a service, but must work out every detail alone. With an SDK, the hard parts are already done, so the work is faster and mistakes are less likely.

A concrete example

A small team is adding card payments to a subscription website written in Python. The payment provider publishes a REST API and an official Python SDK. Calling the API directly would require building request signing, retry logic, webhook signature checks and error parsing, which the team estimates at about two weeks of work.

Using the SDK, a developer installs one package, configures an API key from an environment variable and creates a payment with a single method call. The SDK retries a timed-out request with an idempotency key, so customers are never charged twice, and raises a typed exception when a card is declined. The integration reaches production in three days instead of two weeks, and the team pins the SDK version and reviews its changelog each quarter before upgrading.