System Atlas
the atlas
API · APIs6 minCore

API vs SDK

The contract versus the toolkit that makes the contract pleasant to use.

the gist

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.

ANALOGY // The API is the electrical wiring standard in your walls — voltage, plug shape, the rules. The SDK is the appliance with a plug already attached: it's built to that standard so you just plug in and go.
living diagram01 / 05
Raw APIendpoints · contract
SDKlanguage toolkit
The raw API is the language-neutral contract: you build and send every HTTP request yourself, handling auth, retries and JSON by hand.
01

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.

02

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.

03

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.

04

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.

05

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.

the full picture
01

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.

02

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/charges or GET /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.

03

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.

04

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.

05

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.

what to remember
01

An API is the interface/contract: the endpoints, request/response formats, and rules for talking to a service.

02

An SDK is a language-specific library that wraps an API in native functions, types, and helpers.

03

The SDK is built on top of the API — it makes the same calls, just with less boilerplate.

04

SDKs handle the tedious parts: authentication, retries, pagination, serialization, and error handling.

05

You can always use the raw API directly; the SDK just trades a little flexibility for a lot of convenience.

check yourself

Quick quiz

Q1

What is the relationship between an SDK and an API?

Q2

Which task does an SDK typically handle for you that raw API calls do not?

follow the thread