unkey
  • BlogRead product updates and insights
  • Case studiesPractical results from real deployments
  • ChangelogTrack what shipped, improved, and fixed
  • GlossaryClear definitions for API terms
PricingDocs
Discord
LoginSign Up
  • BlogRead product updates and insights
  • Case studiesPractical results from real deployments
  • ChangelogTrack what shipped, improved, and fixed
  • GlossaryClear definitions for API terms
PricingDocsDiscord
LoginSign Up
  1. Glossary
  2. /SDK

What an SDK Is

Explore with AI
Open in ChatGPTOpen in ClaudeOpen in Perplexity

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

Librarydocsand samples

API

The contract you call

Direct call

HTTP without the library

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.

APISDK
What it isThe contract a server exposesA client package for that contract
How you call itAn HTTP requestA function in one language
How manyOne contractOften one package per language

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 Authorization header.
  • 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:

GET /v1/projects/prj_123 HTTP/1.1
Host: api.example.com
Authorization: Bearer $API_TOKEN
Accept: application/json

A typical JSON response:

{
  "id": "prj_123",
  "name": "billing"
}

The same call through a client library:

import { createClient } from 'example-api';

const client = createClient({
  token: process.env.API_TOKEN,
});

const project = await client.projects.get('prj_123');

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.

On this page

  1. What an SDK is
  2. SDK vs API
  3. What an SDK typically includes
  4. When to use an SDK or call the API directly
  5. Common pitfalls

Turn your API stack into one workflow. Start for free, integrate in minutes, and scale when you need to.

Start for free
unkey

Build better APIs faster

© 2026 Unkey Inc. All rights reserved.

SOC 2 Type II Certified

Company

  • About
  • Careers
  • Status Page
  • Roadmap

Resources

  • Blog
  • Case Studies
  • Changelog
  • Docs
  • Glossary
  • Feature Request
  • Archive

Connect

  • X (Twitter)
  • Discord
  • Book a Call

Legal

  • Terms of Service
  • Privacy Policy
  • Trust Center