Developer SDK

A developer SDK is the type of software development kit most readers meet first: the package a cloud or API provider publishes so that applications can call a service without implementing its wire protocol. The service itself stays remote; the kit is client-side code plus the supporting material that makes the API usable — authentication helpers, configuration loading, samples, and sometimes a command-line tool or local emulator for testing. The encyclopedia describes how this type interoperates with the other three in Developer SDKs and in the subject overview Software development kits.

How it applies

• Scope check before you document. A developer SDK targets a service boundary: a REST API, a gRPC service, a queue, or an event stream. Publishing SDKs target content and output channels, platform SDKs target a host application's extension points, and hardware SDKs target devices and toolchains. Naming the boundary in the first paragraph of a reference set prevents readers from looking for device or plug-in topics that do not exist.
• Generated versus hand-written surface. Much of a developer SDK is produced from an interface definition — an OpenAPI document, a Protocol Buffers file, or a Smithy model — by automatic code generation. Documentation that mixes generated reference output with hand-written guides should keep the two sets separate, because only the hand-written part can carry task context.
• Credentials are a documentation risk area. Kits typically resolve credentials from environment variables, shared configuration files, or an identity provider, in a documented precedence order. Describe that order explicitly and show the least-privilege path; never present a sample with long-lived secrets as the default.
• Transport details leak through. Retry policies, timeouts, pagination, and idempotency keys are usually configurable. Record the defaults, since they change the behavior applications see under load.
• Versioning and support windows. Developer SDKs are usually versioned per language, often under semantic versioning, and independently of the service version. Release notes should state which service API versions a client release speaks to, and which language runtimes it supports.
• Telemetry. Many kits emit logs, metrics, and spans for distributed tracing, which makes them a natural place to document observability setup for calls that cross into cloud services.
• Where the types meet. A publishing pipeline may call a developer SDK to push output to a delivery service; a platform extension may call one to reach a back end; a hardware kit's device agent may report through one. The shared concepts across all four types are interface contracts, authentication, code generation, and abstraction layers.
• Compliance note. Using a provider's developer SDK does not by itself make an integration secure, correct, or compliant with any regulation or standard; obligations rest with the organization that ships the application.

Developer SDK vs. API

An API is the contract: the operations, data shapes, error codes, and serialization format — frequently JSON — that a service exposes. A developer SDK is one packaged client-side implementation of that contract for a specific language, and it may add conveniences the contract does not mention, such as waiters, paginators, or local debugging helpers. Two consequences follow for documentation: the same API can have several SDKs whose method names differ, and a behavior observed through an SDK is not automatically part of the interface contract. When the two disagree, the API reference is the normative source unless the provider states otherwise.

External references

• AWS SDKs and Tools Reference Guide — overview
• Google Cloud — Client libraries and Cloud APIs explained
• gRPC — Core concepts, architecture and lifecycle
• Smithy 2.0 — interface definition language and toolchain
• OpenAPI Generator — client library and SDK generation