Side by side
APIvsSDK
What is the difference between an API and an SDK?
Updated 2 min read7 differences
In short
An API is the set of requests or functions a service offers, while an SDK is a toolkit, usually built on that API, that makes it easier to use from a language.
API
Application Programming Interface
An API is a set of rules that lets one piece of software request data or actions from another in a predictable, documented way.
Read the page on APISDK
Software Development Kit
An SDK (software development kit) is a package of tools, libraries, documentation and examples for building software for a particular platform or service.
Read the page on SDKAPI and SDK compared
| Aspect | API | SDK |
|---|---|---|
| What it is | An interface: the requests or functions on offer | A toolkit for building with a platform or service |
| Contains | A specification, plus the service or library behind it | Libraries, documentation, samples, and often tools |
| Language | Language-neutral for web APIs, such as HTTP and JSON | Made for one language or platform |
| Used through | HTTP requests or function calls | Methods of the SDK's library |
| Handles for you | Nothing beyond the contract | Authentication, retries, pagination, types |
| Required? | Yes, it is how the service is reached | No, it is a convenience on top of the API |
| Example | The endpoints of a payments service | The payments service's Python package |
The difference, explained
An API (application programming interface) is a contract: it lists what you can ask for and what you get back, such as the endpoints of a web service or the functions of a library. An SDK (software development kit) is a package of tools for building on a platform: client libraries, documentation, code samples and sometimes command-line tools or emulators.
For web services the two usually come together. A payments company publishes an HTTP API, and then SDKs for JavaScript, Python and Java that wrap it: instead of building requests and parsing JSON yourself, you call payments.create() and the SDK adds authentication, retries, pagination and types. Everything the SDK does, you could do with the API directly; the SDK saves the work.
For platforms, the SDK is the starting point. Building an Android or iOS app means installing the platform's SDK, which contains the compilers, libraries, emulators and documentation; the platform's APIs are the parts of it your code calls.
A short way to remember it: the API is the menu of what you can order, and the SDK is a set of kitchen tools and recipes for one cuisine. You always use an API, directly or through an SDK; the SDK is optional, and it is only as good as the API underneath.
Which one should you use?
Choose API when…
- No SDK exists for your language, or the official one is out of date.
- You need only one or two calls and don't want another dependency.
- You want full control over requests, timeouts and how errors are handled.
Choose SDK when…
- An official SDK exists for your language and is kept up to date.
- You use many endpoints and want types, autocompletion and fewer mistakes.
- Authentication, retries or pagination would otherwise be yours to write.
Creating a customer, through the API and through an SDK
// Calling the HTTP API directly
const res = await fetch("https://api.example.com/v1/customers", {
method: "POST",
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ email: "ada@example.com" }),
});
if (!res.ok) throw new Error(`API error ${res.status}`);
const customer = await res.json();// The same call through the service's SDK
import { Client } from "example-sdk";
const client = new Client({ apiKey: API_KEY }); // handles auth and retries
const customer = await client.customers.create({ email: "ada@example.com" });Readers ask
Does every API have an SDK?
No. Many APIs, especially small or internal ones, are used directly over HTTP. SDKs are common for large public services, which publish them so more developers can integrate quickly.
Is a library an SDK?
A client library is often the main part of an SDK, but an SDK usually adds more around it: documentation, samples and tools. The words overlap, and many companies call a single client library their SDK.
Can an SDK hide problems in the API?
It can smooth them over, with retries or friendlier errors, but it can't change what the API allows. If the API is missing a feature, the SDK is missing it too.