What an SDK Is
TL;DR
An SDK (software development kit) is a library, docs, and samples for one language. The API is the contract on the server. The SDK is a client that calls that contract for you.
SDK
API
Direct call
An SDK (software development kit) is a bundle of tools for building on a specific platform. For an HTTP API, that bundle is usually a client library, documentation, and sample code. You install the library, configure a credential, and call functions. The library turns those calls into requests.
The API is the contract on the server. The SDK is one client for that contract.
What an SDK is
The name covers any toolkit aimed at one platform: a language, an operating system, a device, or a network API. In API work it almost always means the client library and the docs shipped with it.
A method on that client builds a URL, sets headers, sends the request, and returns a value or a structured error. The service that answers the request is still the API. A Python package and a Java package can both call the same API. They are different SDKs, with different release cycles.
SDK vs API
An API names the resources, the methods, the fields, and the errors. A REST API exposes that contract over HTTP. Any program that can send an HTTP request can use it.
An SDK sits in front of that contract, in one language. It encodes choices the raw API leaves open: where the token goes, how a JSON body becomes objects, how to walk a paginated list, and whether a failed call is retried.
An API works with no SDK. Callers then use the HTTP client already in their stack. An SDK is optional packaging around the same contract. When the API adds a field, each package has to catch up in its own release.
The methods you import are a view of the API. They are not a separate interface the server implements.
What an SDK typically includes
Three pieces show up in almost every API kit.
Library. The code you import. Methods map to endpoints, and types describe requests and responses. This is the part that ships inside your application.
Documentation. A reference for those methods, the setup steps, and the errors the library surfaces. Useful docs name the API version they match.
Samples. Small programs that configure the client and call one or two methods. A sample shows the intended setup without the whole reference.
Kits often add more:
- Authentication helpers, so each call does not rebuild the
Authorizationheader. - Pagination helpers that follow a cursor until the list ends.
- Retry and timeout defaults.
- A changelog, and sometimes a command-line tool that uses the same client.
Generated kits start from a machine-readable description such as OpenAPI. The description lists the endpoints, and a generator emits the library. Hand-written kits do the same job with code a person maintains. In both cases the server contract is the source of truth, and the library is a client.
When to use an SDK or call the API directly
Use an SDK when the API is a large part of the product and a maintained client exists for your language. Typed methods catch a bad field name before you ship. Shared helpers keep authentication and pagination consistent. Another service in the same language can import the same package.
Call the REST API directly when a dependency would be more code than the requests. That is the better fit when you only need one or two endpoints, when no current SDK exists for your language, or when the published client is far behind the API. Send the request yourself when you are checking a status code, a header, or a body the helper does not expose. A short script can also stay on the HTTP tools already installed on the machine.
Both options hit the same server. A direct call uses an HTTP client. The SDK uses one too, inside the library.
A direct request for a single resource:
A typical JSON response:
The same call through a client library:
projects.get builds the GET request, sends the token, and returns the parsed project. If you need a status code or a header that method does not return, send the HTTP request.
Common pitfalls
The SDK lags the API. A new field or endpoint can ship on the server before any client package knows about it. Call that endpoint over HTTP, or generate a client from the current description, when you need the field before the package release.
Retries and timeouts are implicit. A library may retry a timed-out POST, or wait longer than the caller's budget. Read the defaults before you put the client on a user-facing path. Set a timeout that fits the caller, and retry only when sending the request twice is safe.
Errors get flattened. Some clients turn every failure into one exception and drop the body. If you branch on 404 versus 409, confirm the library still gives you the status and the response body.
The dependency is larger than the feature. A generated client can include every endpoint, plus its own HTTP stack. That cost fits when you use the API broadly. For a single endpoint, a direct request is smaller.
Samples leak credentials. Load the real token from the environment, as the sample above does, and keep it out of the repository.
Versions drift. Pin the SDK the way you pin any other library. A major bump can rename methods even when the API stayed the same. Read the changelog, and upgrade on purpose.
The API remains the contract. The SDK is a maintained shortcut to it, useful when the package is current and its defaults match how you call the service.
Questions & Answers about SDK
An SDK, or software development kit, is a set of tools for building against a platform or an API. For an API, that usually means a client library, documentation, and sample code in one language. You install the package and call functions. The SDK sends the HTTP requests.
