SDK Design
SDK design is the practice of building client libraries that let developers call an API comfortably in their own language. It covers client shape, naming, sync and async methods, error handling, authentication, versioning, and the tests and docs that ship with the package, so the SDK feels like a native library rather than a thin HTTP wrapper.
itSoftware engineering | OpenSkills.info
Course pathWalk it in order
Look it upDip in anytime
Go furtherLeaves this page
Intro
SDK Design
An SDK, or software development kit, is the client library developers use to call your API from their own language. The API defines what the service accepts and returns. The SDK decides how that contract feels in Python, TypeScript, Go, or .NET. A well-designed SDK packages transport, serialization, authentication, retries, and paging behind code that reads like a native library, not like a wrapper around HTTP.
SDK design is a product decision, not a code generation step you run and forget. Every surface you publish becomes part of the package's promise to consumers: the client's constructor, the method names, the errors they catch, and the versions they pin. Design decisions made here are visible in every file a consumer writes.
Start from the API contract
Read the API description before you pick method names. The API defines the resources, operations, inputs, outputs, and failure modes your SDK must express. A machine-readable contract, such as an OpenAPI document, gives the SDK author a complete list of operations and schemas to cover, which is why generators use it as their input.
Do not let the SDK invent a parallel model. Azure's guidelines stress consistency: client libraries should stay consistent with the service they wrap, within the target language, and across the languages the service publishes. When those conflict, idiomatic use of the target language wins, but the service concepts stay recognizable. If the API has a Customer resource with list, get, and update operations, the SDK should expose those as methods on a customer client, not as a free-form HTTP utility.
Shape one client per service
Continue the course
This section is part of the paid course.
See pricing to subscribe, or log in if you already have access.
Where this skill leads
Relevant careers
See how this topic contributes to broader role-level skill maps.
Sources
- https://azure.github.io/azure-sdk/general_design.html
Supports
- Client library design principles: idiomatic surfaces, consistency within a language, and treating the SDK as a product
- Service client naming, construction, lifecycle, thread safety, and per-service client scope
- Method design, sync and async parity, cancellation, pagination, and long-running operation handles
- Error handling through typed exceptions and stable error codes that distinguish client, service, and retryable failures
- Authentication through credential abstractions and token refresh
- Documentation, samples, and test expectations for released libraries
- https://azure.github.io/azure-sdk/typescript_design.html
Supports
- Language-specific guidance for naming, async methods, cancellation, and pageable and long-running-operation shapes in TypeScript clients
- https://cloud.google.com/apis/design
Supports
- Resource-oriented design background that client method shapes should mirror rather than re-imagine
- Standard and custom methods, resource names, and consistent field conventions
- https://google.aip.dev/client-libraries/4210
Supports
- Client library generators as a way to produce consistent client libraries from API definitions
- GAPIC generator behavior and the role of generated versus handwritten library parts
- https://github.com/googleapis/gapic-generator
Supports
- Google's open-source client library generator for APIs defined with gRPC and protobuf descriptors
- https://docs.stripe.com/sdks
Supports
- SDK support lifecycle and semantic versioning of client libraries
- Independent versioning of the SDK package and the pinned API version
- Stability expectations that let consumers upgrade an SDK without forcing an API upgrade
- https://semver.org/
Supports
- Major, minor, and patch semantics and the breaking-change definition
- Version communication for published client libraries
- https://spec.openapis.org/oas/v3.1.0.html
Supports
- OpenAPI revision history: Swagger 1.0 in 2011, Swagger 2.0 in 2014, donation to the OpenAPI Initiative in 2015, and later revisions
- OpenAPI as the common machine-readable input to SDK generators
- https://github.com/OpenAPITools/openapi-generator
Supports
- Generating client libraries, server stubs, and documentation from an OpenAPI document across many languages
- The project's May 2018 fork from swagger-codegen and its history
- Template customization and generated-code licensing behavior
- https://github.com/swagger-api/swagger-codegen
Supports
- The original generator that produces client libraries and server stubs from OpenAPI or Swagger descriptions
- https://smithy.io/2.0/index.html
Supports
- Smithy as a protocol-agnostic interface definition language built for code generation
- One model driving clients, servers, documentation, and OpenAPI output
- Smithy's origin at AWS and its use in generating AWS SDKs
- https://github.com/smithy-lang/smithy
Supports
- Smithy's open-source release and Apache 2.0 license
- The repository's March 2019 public creation date
- https://aws.amazon.com/blogs/developer/introducing-smithy-idl-2-0/
Supports
- Smithy IDL 2.0 release on 11 August 2022 and its code-generation improvements: reduced nulls and optionals, enums, mixins, and defaults
- https://grpc.io/blog/ga-announcement/
Supports
- gRPC 1.0 release on 23 August 2016 and a stable protocol surface for proto-driven client generation
- https://azure.microsoft.com/en-us/blog/previewing-azure-sdks-following-new-azure-sdk-api-standards/
Supports
- The July 2019 preview wave of the redesigned Azure SDKs built on open guidelines and a shared core library
- https://learn.microsoft.com/en-us/openapi/kiota/
Supports
- Kiota as a command-line generator that emits only the client surface a caller uses, building on a shared core library
- Supported languages and OpenAPI and JSON Schema coverage
- https://devblogs.microsoft.com/microsoft365dev/tailored-sdk-experiences-via-kiota-now-generally-available/
Supports
- Kiota general availability on 16 March 2023 and its strongly typed, minimal generated client model
- https://github.com/microsoft/api-guidelines
Supports
- Cross-organization naming, versioning, and error conventions that SDK authors often need to encode into client surfaces
- https://github.com/marmelab/awesome-rest
Supports
- A curated index of REST API architecture, development, test, and performance resources used to select the awesome links
- https://github.com/oapi-codegen/oapi-codegen
Supports
- Generating typed Go clients and server code from OpenAPI documents
- https://github.com/hey-api/openapi-ts
Supports
- Generating typed TypeScript clients from OpenAPI documents
- https://opensource.zalando.com/restful-api-guidelines/
Supports
- A real-world, requirements-oriented API guideline set that SDK design work references for naming, versioning, and error consistency
- https://apis.guru/
Supports
- A directory of public, OpenAPI-described APIs to practice SDK design and generator output against
- https://speakeasy.com/
Supports
- Speakeasy SDK generation, changelog, and documentation products and their proprietary, freemium positioning
- https://liblab.com/
Supports
- liblab SDK generation service and its proprietary, freemium positioning
- https://www.buildwithfern.com/
Supports
- Fern SDK and documentation generation from OpenAPI and its open-core, freemium model
- https://www.stainless.com/
Supports
- Stainless SDK generation service and its proprietary, freemium positioning