API vs SDK
The contract versus the toolkit that makes the contract pleasant to use.
An API is the raw interface — the set of endpoints, messages, and rules a service exposes. An SDK is a language-specific toolkit built on top of that API, wrapping the raw HTTP calls in native functions, and handling auth, retries, types, and serialization for you. The API is the contract; the SDK is the convenience layer that speaks it for you.
The API is the contract
An API (Application Programming Interface) is the raw, language-neutral interface a service exposes: its endpoints, the shape of requests and responses, the authentication scheme, and the rules for using them. It is a contract — 'send me a request in this format and I'll answer in that format' — and nothing more. Any program in any language can talk to it directly by making HTTP calls, as long as it follows the contract.
The SDK is the toolkit
An SDK (Software Development Kit) is a language-specific library that packages up everything you need to work with an API from a particular language. Instead of hand-crafting HTTP requests, you call native functions like stripe.charges.create(...) that feel like part of your own codebase. The SDK exposes typed objects, helper methods, and idiomatic error handling tailored to Python, JavaScript, Go, or whatever you're writing in.
The SDK is built on the API
Crucially, an SDK does not replace the API — it sits on top of it. Under the hood, every SDK method ultimately makes the very same HTTP calls to the very same endpoints you could call yourself. The SDK is a wrapper that translates convenient native function calls into raw API requests and translates the raw responses back into native objects. Change the API and the SDK must be updated to match.
What the SDK does for you
The value of an SDK is everything tedious it handles automatically: attaching authentication headers, retrying failed requests with backoff, following pagination, serializing and deserializing JSON, and surfacing errors as native exceptions. It turns dozens of lines of boilerplate into a single, readable call. That convenience is why providers ship official SDKs — they lower the barrier to adopting their API.
Choosing between them
Use the SDK when one exists for your language and you want to move fast with less boilerplate and fewer bugs. Drop down to the raw API when there's no SDK for your stack, when you need behavior the SDK doesn't expose, or when you want to minimize dependencies. The trade is convenience versus control — but since the SDK just wraps the API, you can always mix both.
Two words people mix up
API and SDK get used almost interchangeably in casual conversation, but they name two genuinely different things, and the difference is easy to pin down once you see it: an API is an interface, and an SDK is a toolkit. One is the contract a service exposes; the other is a package of tools that helps you use that contract from a specific programming language. Understanding the distinction clears up a surprising amount of confusion about how software talks to other software.
The cleanest one-line version is this: the **API defines *what* you can do, and the SDK gives you convenient tools to *do* it** in your language of choice. An API is something a service *has*; an SDK is something a service *provides to help you consume the API*. They are not competitors and not alternatives — an SDK is quite literally built on top of an API, which is why the rest of this comes down to understanding that layering.
What an API is
An API (Application Programming Interface) is a defined interface through which one piece of software talks to another. For a web service, the API is the concrete set of things it exposes to the outside world:
- The endpoints you can call, like
POST /v1/chargesorGET /v1/customers/42. - The format of requests and responses — typically JSON with a documented schema.
- The authentication scheme, such as an API key or an OAuth token.
- The rules governing use: rate limits, required headers, error codes.
The defining quality of an API is that it is a contract, and a language-neutral one. It says, in effect, "send me a request shaped like this and I will respond shaped like that." It does not care whether the caller is written in Python, JavaScript, Go, or Rust. Any program in any language can use the API directly, as long as it can make HTTP requests and follow the documented format. That universality is the API's strength — and also the source of the friction that SDKs exist to remove.
What an SDK is
An SDK (Software Development Kit) is a language-specific toolkit for working with a service, and its core component is usually a client library that wraps the API. Where the API is neutral and raw, the SDK is opinionated and native.
Instead of manually constructing an HTTP request — assembling the URL, setting the Authorization header, JSON-encoding the body, sending it, checking the status code, and parsing the response — you call a function that already belongs to your language:
- In Python:
stripe.Charge.create(amount=2000, currency="usd") - In JavaScript:
await stripe.charges.create({ amount: 2000, currency: "usd" })
That single line does everything the manual version did, but it reads like ordinary code in your project. A good SDK also ships typed objects so your editor autocompletes fields and catches mistakes at compile time, idiomatic error handling that raises native exceptions instead of leaving you to inspect status codes, and often extra helpers and utilities beyond the raw API — things like webhook signature verification or pagination iterators. The SDK's whole job is to make the API feel like a natural extension of the language you're already writing.
The SDK is built on top of the API
This is the point that ties everything together and the one worth getting exactly right: an SDK does not replace an API — it is built on top of one.
Under the hood, every method an SDK exposes ultimately makes the very same HTTP calls to the very same endpoints that you could make yourself with curl. When you call stripe.charges.create(...), the SDK internally constructs a POST request to /v1/charges, attaches your API key, serializes your arguments into the request body, sends it, and then parses the JSON response back into a native Charge object for you to use. It is a wrapper: convenient native calls in, raw API requests out, native objects back.
Two consequences follow directly from this layering. First, anything an SDK can do, you can do with the raw API — the SDK adds no new capabilities, only convenience, because it is limited to what the underlying API offers. Second, the SDK is downstream of the API: if the provider changes the API, the SDK must be updated to match, which is why SDKs are versioned to track the API they wrap. The API is the source of truth; the SDK is a faithful translator.
When to use which
Because an SDK is just a convenience layer over the API, the choice between them is a practical trade-off between speed and control rather than an either/or decision.
Reach for the SDK when an official one exists for your language, which is most of the time for popular services. You will write far less code, introduce fewer bugs in the tedious plumbing — authentication, retries with exponential backoff, pagination, serialization — and get types and autocomplete for free. This is why providers invest in shipping high-quality SDKs across many languages: a smooth SDK dramatically lowers the barrier to adopting their platform, so it is in everyone's interest.
Drop down to the raw API when there is no SDK for your stack, when you need some behavior or new endpoint the SDK hasn't exposed yet, when you want to minimize dependencies in a lean environment, or when you're debugging and need to see exactly what's on the wire. Because the SDK sits on top of the same API, you're never locked in — you can use the SDK for the common paths and hand-craft a raw request for the one edge case it doesn't cover. The mental model to keep is simple: the API is the interface, the SDK is the toolkit built on it, and knowing which layer you're working at tells you exactly what you're trading away.
An API is the interface/contract: the endpoints, request/response formats, and rules for talking to a service.
An SDK is a language-specific library that wraps an API in native functions, types, and helpers.
The SDK is built on top of the API — it makes the same calls, just with less boilerplate.
SDKs handle the tedious parts: authentication, retries, pagination, serialization, and error handling.
You can always use the raw API directly; the SDK just trades a little flexibility for a lot of convenience.
Quick quiz
What is the relationship between an SDK and an API?
Which task does an SDK typically handle for you that raw API calls do not?
What is a REST API
The architectural style that made the web's APIs feel like the web itself.
API design best practices
The conventions that make an API feel obvious instead of hostile.
MCP vs API vs A2A protocol
Three connectors for three different conversations — apps, models, and agents.