API vs SDK
The interface vs the toolkit
An API defines how two systems communicate with each other, while an SDK is a complete toolkit that helps developers build applications for a specific platform. SDKs often contain APIs, but APIs exist independently of SDKs.
API
An API (Application Programming Interface) is a contract that defines how software components interact. It specifies the available operations, their inputs and outputs, and the communication protocol. Web APIs (often called REST APIs or GraphQL APIs) use HTTP to let different systems exchange data. But APIs aren't limited to the web — operating systems, libraries, and hardware all expose APIs. An API is an abstraction layer: it tells you what you can do without exposing how it's done internally. The Stripe API lets you charge credit cards, the Twitter API lets you fetch tweets, and the DOM API lets JavaScript manipulate web pages.
SDK
An SDK (Software Development Kit) is a comprehensive package of tools, libraries, documentation, code samples, and sometimes IDEs that help developers build applications for a specific platform. The iOS SDK includes compilers, simulators, UI frameworks, and APIs needed to build iPhone apps. The AWS SDK for Python (boto3) wraps AWS APIs into convenient Python classes. SDKs provide higher-level abstractions that handle authentication, serialization, error handling, retries, and other boilerplate so developers can focus on their application logic rather than low-level API calls.
Key Differences
- **Scope**: An API is an interface specification. An SDK is a complete development toolkit that usually wraps one or more APIs. - **What you get**: An API gives you endpoints to call. An SDK gives you libraries, tools, documentation, and code samples. - **Abstraction level**: APIs are low-level — you construct requests manually. SDKs are high-level — they handle request construction, auth, and error handling. - **Language specificity**: APIs are language-agnostic (any language can call an HTTP API). SDKs are built for specific programming languages. - **Dependency**: SDKs typically contain or wrap APIs. APIs don't require SDKs — you can call them with raw HTTP. - **Example**: Stripe's API is the HTTP endpoints. Stripe's Python SDK (stripe-python) wraps those endpoints in Python classes.
When to Use Each
**Use an API directly** when no SDK exists for your language, when you need minimal dependencies, when you're making simple one-off requests, or when you want maximum control over request construction. **Use an SDK** when one is available for your language and platform. SDKs save significant development time by handling auth flows, request signing, pagination, retries, and type safety. For complex platforms like AWS, GCP, or Stripe, the SDK is almost always the better choice.
Analogy
**An API** is like a restaurant menu — it lists everything available, what you need to order it (parameters), and what you'll get back (responses). You interact with the kitchen only through this menu. **An SDK** is like a meal kit delivery service — it gives you the menu, the pre-measured ingredients, step-by-step recipes, and specialized utensils. You could buy the ingredients yourself (call the API directly), but the kit makes it much faster and harder to mess up.