API vs SDK, explained with a recipe and a meal kit

The short version#

An API (application programming interface) is the set of rules a service publishes so other software can talk to it: what you can ask for, in what format, and what comes back. An SDK (software development kit) is a package of ready-made code, usually for one programming language, that follows those rules for you. You can always use an API without an SDK. You can’t really use an SDK without an API, because the SDK is just a convenient way of calling it.

Side by side#

	API	SDK
What it is	A published contract between two systems	A code library (plus docs and samples) built on that contract
Who it’s for	Any software that can send web requests	Developers working in a specific language
Language	Language-neutral	One per language (Python, Java, JavaScript and so on)
What you get	Endpoints, data formats, error codes	Functions, error handling, retries, sign-in helpers
Updates	Versioned by the vendor	Versioned separately; you choose when to upgrade
Can you skip it?	No, it’s the way in	Yes, a developer can call the API directly

The analogy: a recipe and a meal kit#

The API is a recipe. It lists the ingredients, the quantities and the steps. Anyone can follow it with their own pots and pans.

The SDK is a meal kit built from that recipe. The onions are already chopped, the spices are pre-measured, and there’s a card that tells you which bag goes in first. You’ll get the same dish faster and with fewer mistakes, but only if you cook in the kitchen the kit was designed for. A kit made for a gas stove (a Python SDK, say) won’t help someone cooking on an induction hob (a team writing in Go), unless there’s a kit for that too.

How they stack up#

1
   Your application code
2
           |
3
           v
4
  +-------------------+     the shortcut: ready-made
5
  |   SDK (optional)  |     functions like createInvoice()
6
  +-------------------+
7
           |
8
           v
9
  +-------------------+     the contract: endpoints,
10
  |        API        |     formats, rules, versions
11
  +-------------------+
12
           |
13
           v
14
     Vendor's service

Whether your developer goes through the SDK or straight to the API, the request lands at the same place. For the bigger picture of how systems connect, see our explainer on middleware software.

A real example#

Stripe, the payments company, publishes its API reference and also official SDKs for server-side languages including Ruby, Python, Go, Java, Node, PHP and .NET. The page says Stripe versions its SDKs with semantic versioning (a numbering scheme where the first number goes up when changes could break existing code) and versions its API by release date. In practice, that means two separate things to keep current: the API version your account uses, and the SDK version your code uses.

Decision factors#

Is there an official SDK for your team’s language? If yes, it usually saves time. If the only SDKs are community-built, check how recently they were updated.
How much of the API do you need? Calling two endpoints doesn’t justify adding a library. Building a full product on a vendor does.
Who maintains it? An SDK is a dependency. When the vendor releases a new major version, someone has to upgrade and retest.
Are you using a no-code tool? Automation platforms call APIs for you, so the SDK question usually doesn’t arise.

What this means for a 20-person company

If you don’t employ developers, you’ll rarely touch an SDK. Your integration tool or agency will.

When an agency quotes for custom work, ask whether they’ll use the vendor’s official SDK, and who upgrades it.

“Has an SDK” is a mild plus on a vendor scorecard. “Has a public, documented API” is the requirement.

Also consider

Client libraries and wrappers: other names for SDK-style code; some are official, some community-made.

Command-line tools: many vendors ship one alongside the SDK for scripting and testing.

OpenAPI files: a machine-readable API description that can generate SDKs automatically.