API vs. SDK

API and SDK are related, but they solve different problems. An API defines how software components communicate. An SDK packages tools that help developers use that interface correctly and productively. Confusing the two leads to weak integration design and poor developer experience.

What an API is

An API, or Application Programming Interface, is the contract exposed by a system. It defines operations, request and response structures, authentication rules, error handling, and any guarantees around ordering, idempotency, or consistency. APIs can be network-based, such as REST or GraphQL endpoints, or local, such as a library interface inside one process.

The key property is that the API is the boundary. It tells a caller what the system accepts and what it returns.

What an SDK adds

An SDK, or Software Development Kit, wraps one or more APIs with implementation support. That might include typed clients, authentication helpers, retry logic, pagination utilities, local testing tools, command-line helpers, or sample applications. A good SDK reduces accidental complexity so integrators spend more time using the product than re-implementing boilerplate.

The SDK is therefore opinionated. It chooses defaults, exposes common workflows, and smooths over transport details. That convenience can be powerful, but it also means the SDK must be maintained carefully as the underlying API evolves.

Why the distinction matters in practice

If you publish only an API, every client team must solve authentication, retries, error classification, and object modelling on its own. That can be acceptable for simple internal services or very narrow integrations. It becomes painful when the product is public-facing or used across multiple languages.

If you publish only an SDK without a clear underlying API contract, users can become dependent on hidden behaviour or language-specific quirks. That makes support and cross-platform parity harder.

When to provide one versus both

Most platforms should think in layers. The API is the stable system contract. SDKs are curated access paths for popular developer environments. That separation preserves flexibility. Advanced users can call the raw API directly. Most users can rely on the SDK for faster onboarding and safer defaults.

It is also acceptable to stop at the API when the audience is small or the workflows are highly customised. Conversely, some products distribute local SDKs with no network API at all, such as graphics frameworks or embedded libraries. The right choice depends on who is integrating and what complexity you want them to absorb.

The practical rule is simple: design the API for correctness and long-term compatibility, then design the SDK for ergonomics. One is the contract. The other is the toolkit that makes the contract pleasant to use.