Sdk Engineer

SDK Engineer

When to Use

• Design or implement client SDKs and API client libraries for public or partner APIs
• Align SDK surface area with OpenAPI, GraphQL schema, protobuf, or RPC contracts
• Model resources, operations, pagination, streaming, and error types in client code
• Implement authentication flows (API keys, OAuth2, HMAC/signing, mTLS hooks)
• Define retries, timeouts, idempotency keys, and resilience defaults for SDK users
• Plan versioning, deprecation, and multi-language SDK parity (naming, packaging, semver)
• Author quickstarts, examples, and SDK docs that match the API reference
• Build contract tests and integration tests against sandboxes or recorded fixtures

When NOT to Use

• Design the backend API or service only without a client library → api-development, senior-software-engineer, enterprise-integration-api-developer
• Build end-user application UI or product frontends → senior-frontend-software-engineer, fullstack-software-engineer
• Stand up internal developer platforms, golden paths, or portals without SDK product work → platform-engineer
• Write documentation or tutorials without implementing or evolving an SDK → tech-writer-researcher
• Run pre-flight architecture or build go/no-go reviews without SDK delivery → build-validator

Related skills

Core Workflows

1. Scope and contract intake

1. Identify API style (REST, GraphQL, gRPC, JSON-RPC) and source of truth (OpenAPI, proto, schema registry) 2. List target languages/runtimes and distribution (npm, PyPI, Maven, Go module, crates.io) 3. Define non-goals (server implementation, CLI-only wrappers, codegen-only with no hand layer) 4. Capture breaking-change policy and minimum supported API version

See `references/sdk_engineer_scope.md`.

2. Client modeling and public surface

Map contract operations to idiomatic client types: resources, services, request builders, and enums.

1. Prefer stable resource-oriented names over raw URL paths in public API 2. Hide transport details; expose optional raw request escape hatches for power users 3. Keep configuration (base URL, credentials, timeouts) on a single client instance 4. Document thread-safety / async model per language

See `references/api_contracts_and_client_modeling.md`.

3. Auth, resilience, and errors

1. Implement credential providers and token refresh without surprising global state 2. Apply default timeouts; retry only idempotent operations with bounded backoff + jitter 3. Map HTTP/gRPC status and error bodies to a typed error hierarchy with request IDs 4. Support idempotency keys where the API documents them

See `references/auth_retries_and_resilience.md`.

4. Pagination, streaming, and large payloads

1. Implement cursor/page iterators that compose cleanly (for await, generators, paginators) 2. Support streaming RPC or SSE where the contract requires partial results 3. Avoid buffering unbounded collections; document memory trade-offs

See `references/pagination_streaming_and_resources.md`.

5. Versioning and compatibility

1. Ship SDK semver independent of API version where possible; document mapping 2. Add deprecation warnings, sunset dates, and migration snippets in release notes 3. Run compatibility suites against N API versions when feasible

See `references/versioning_and_compatibility.md`.

6. Testing and documentation

1. Contract tests: generated or hand-written against OpenAPI/proto examples 2. Integration tests: sandbox credentials, VCR/fixtures, or ephemeral environments 3. Align README, quickstart, and reference docs with the official API catalog 4. Publish runnable examples in CI

See `references/sdk_testing_and_documentation.md`.

When to load references

API Contracts and Client Modeling

Source of truth

Rule: Server behavior wins over stale specs—file spec bugs upstream; do not encode undocumented server quirks without explicit versioning.

OpenAPI-first workflow

1. Pin spec URL or commit hash in SDK repo 2. Run codegen (optional) into generated/ namespace 3. Add hand-written public types that hide generated noise 4. Diff spec on CI; fail on breaking changes unless major SDK bump planned 5. Map components.schemas to resource classes; avoid anonymous nested objects in public API

Naming

• Use stable business names (Customer, Invoice) not path segments (V1CustomersPost)
• Prefer verbs on client services: customers.create, invoices.list
• Align enum names with server; document unknown enum handling (UNSPECIFIED, string fallback)

Request builders

Expose optional fields via builders or keyword args—not positional lists of 12 parameters.

client.invoices.create(
  customer_id="cus_123",
  amount=1000,
  currency="usd",
  idempotency_key="idem-uuid",  # when supported
)

Response modeling

• Distinguish full resource vs summary types when OpenAPI uses different schemas
• Parse dates as language-native instants with explicit timezone policy (UTC default)
• Represent money as integer minor units + currency code unless API uses decimal strings (document parsing)

GraphQL client modeling

• Colocate operations with types; avoid mega-query strings in consumer apps
• Expose variables objects; validate required variables before network call
• Handle errors[] + partial data per GraphQL spec
• Support persisted query hashes only when server documents them

gRPC modeling

• Set deadlines per call; document default deadline on client
• Map metadata for auth tokens and trace propagation
• Wrap streaming iterators with cancellation tied to context/deadline
• Keep proto package version aligned with server deployment matrix

Configuration object

Single entry point:

Escape hatches

Provide raw_request / low-level access for:

• Beta endpoints not yet in spec
• Custom headers required by support
• Debugging with exact wire format

Document that escape hatches are not covered by semver guarantees.

Multi-language considerations

Parity does not require identical names—require identical semantics (auth, retries, error codes).

Contract drift detection

• CI job: fetch spec, diff against pinned version
• Breaking: removed operation, required field added to request, enum value removed
• Non-breaking: new optional field, new operation, new enum value (if clients tolerate unknowns)

Review checklist

• [ ] Every public method maps to documented server operation
• [ ] Required auth documented per operation (security schemes in OpenAPI)
• [ ] List operations return iterator/paginator, not opaque next-page token only
• [ ] Unknown JSON fields preserved or ignored per language convention (document which)

Authentication, Retries, and Resilience

Authentication patterns

API keys

• Send via header name defined in spec (Authorization, X-Api-Key)—never query string unless API requires it
• Read from environment variable in examples; never log key values
• Support rotation: allow updating provider without reconstructing entire app graph when possible

OAuth2 (client credentials, authorization code)

• Encapsulate token fetch + refresh in a credential provider
• Refresh proactively before expiry (skew 30–60s)
• Serialize refresh to avoid stampedes; surface AuthenticationError on failure
• Document required scopes per operation where server enforces scope

Request signing (HMAC, AWS SigV4-style)

• Canonicalize method, path, query, body hash per server rules
• Clock skew: document NTP requirement; include signing timestamp in errors on failure
• Unit-test vectors from server docs or golden fixtures

mTLS

• Expose hooks to supply client cert/key or custom TLS context
• Document certificate rotation for long-running services

Transport defaults

Retry policy

Retry when

• HTTP 408, 429, 5xx (if API does not document otherwise)
• gRPC UNAVAILABLE, RESOURCE_EXHAUSTED (with backoff)
• Network resets, TLS handshake transient failures

Do not retry when

• 4xx except 408/429 (unless API documents retryable code)
• Non-idempotent methods without idempotency key support
• Business logic errors encoded as 200 with error envelope (map to non-retryable)

Backoff

• Exponential backoff with full jitter
• Cap max attempts (typically 3–5)
• Honor Retry-After on 429 when present

delay = min(cap, base * 2^attempt) * random(0.5, 1.0)

Idempotency keys

• Accept idempotency_key on create/charge/payment operations when server supports
• Generate UUID v4 if caller omits; document collision behavior
• Retries must reuse same key for same logical operation

Timeouts and cancellation

• Propagate cancellation (context, AbortSignal, asyncio cancel)
• Document that cancel does not guarantee server-side abort unless API supports it
• On cancel, do not retry unless caller explicitly opts in

Error taxonomy

Map wire errors to a small hierarchy:

Include when available:

• HTTP status / gRPC code
• Server error_code string
• request_id / trace id
• Raw body attachment for support (redact secrets)

Circuit breaking (optional)

• Expose optional breaker hook—not mandatory in v1 SDKs
• When integrated: open after error rate threshold; half-open probe
• Document interaction with retries (retry inside breaker only when appropriate)

Logging and secrets

• Log method, path template, status, latency, request id—not bodies with secrets
• Provide debug mode that redacts Authorization and signed headers
• Never include tokens in exception messages

Testing resilience

• Table-driven tests for retry counts and backoff timing (inject clock)
• Simulate 429 with Retry-After
• Verify no retry on 400/401/403/404
• Verify idempotency key stable across retries

Defaults documentation template

Ship a Defaults section in README:

## Defaults
- Connect timeout: 10s
- Read timeout: 60s
- Retries: 3 attempts on idempotent GET/HEAD and on 429/5xx with jitter
- POST retries: disabled unless `idempotency_key` is set

Pagination, Streaming, and Resources

Pagination goals

• Hide cursor/page token mechanics behind iterators
• Fetch next page lazily (do not buffer entire dataset by default)
• Preserve server ordering guarantees documented in API reference
• Surface has_more / empty page without throwing

REST pagination patterns

Iterator API (language-agnostic)

pager = client.items.list(limit=100, filters={...})
for item in pager:        # auto-fetches pages
    process(item)

# or manual
while pager.has_next():
    page = pager.next_page()

Parameters

• Pass through filter/query params on first request only unless API requires repeat
• Allow max_items safety cap for runaway jobs
• Document default page size and server max limit

GraphQL pagination

• Relay cursors: first/after, pageInfo.hasNextPage, endCursor
• Combine with operation-specific filters
• Avoid N+1: use batch fields or dataloaders in app code; SDK provides cursor helper only

gRPC streaming

Set deadlines per stream; document heartbeat/ping if server requires keepalive.

HTTP streaming (non-gRPC)

• SSE: parse event: blocks; reconnect policy documented if API supports Last-Event-ID
• Chunked JSON lines: NDJSON parsers with buffer limits
• File download: stream to disk; expose progress callback optional

Resource lifecycle helpers

Some APIs combine pagination with sub-resources:

customer = client.customers.retrieve("cus_123")
for invoice in customer.invoices.list():  # nested paginator
    ...

Prefer flat client.invoices.list(customer_id=...) unless nesting is idiomatic in target language.

Partial responses and field selection

• Support fields, expand, include query params when spec defines them
• Type expanded relations as optional nested objects
• Document extra round-trips when expansion unavailable

Uploads and downloads

• Multipart upload: expose stage helpers (init, parts, complete) matching API
• Resumable uploads: persist upload id client-side
• Downloads: stream with checksum validation when server provides digest

Memory and performance

• Default: O(page size) memory per iteration
• Opt-in collect_all() with loud warning in docs
• Parallel page prefetch: advanced; off by default to avoid rate limits

Error handling mid-sequence

• If page 3 fails mid-iteration: raise with cursor position in error metadata when possible
• Document whether iteration is resumable from last cursor
• Do not silently skip failed pages

Testing pagination

• Fixture files: 2–3 pages with different cursors
• Assert single HTTP call per next_page() when cache disabled
• Assert stop when empty or has_more=false
• Property test: union of all pages equals known fixture set (test harness)

Documentation examples

Every list operation in README should show one iterator example:

for item in client.resources.list(status="active"):
    print(item.id)

Avoid only showing low-level GET /v1/resources?page=2 unless demonstrating escape hatch.

SDK Engineer — Scope and Boundaries

Purpose

Define what an SDK engineer owns when delivering API client libraries: contract fidelity, developer experience, resilience defaults, lifecycle management, and testable documentation—not server implementation or unrelated platform work.

In scope

Out of scope (route to peers)

API styles covered

• REST/HTTP + JSON — OpenAPI 3.x primary; hand-crafted ergonomic layer on generated stubs when needed
• GraphQL — operations, fragments, persisted queries; avoid leaking raw HTTP unless documented
• gRPC — protobuf services, deadlines, metadata, streaming RPCs
• RPC-style JSON — JSON-RPC, Solana-style RPC, WebSocket subscriptions where applicable

Engagement phases

Discover

• Read official spec (OpenAPI, GraphQL SDL, .proto)
• Inventory existing SDKs, codegen tooling, and consumer complaints
• Agree target languages and release cadence

Design

• Publish SDK API proposal: naming, config, error model, pagination pattern
• Review with API owners for breaking vs additive changes
• Decide codegen vs hand-written ratio per language

Build

• Implement core client, auth, errors, pagination
• Add examples and contract test harness
• Wire CI: lint, unit, contract, optional integration

Maintain

• Track server deprecations; emit client warnings
• Patch security issues in auth/transport promptly
• Measure adoption (download stats, support tickets, time-to-first-call)

Success criteria

• New integrator completes first successful call in <15 minutes using quickstart alone
• Contract tests pass on every PR against pinned spec revision
• Breaking SDK releases ship with migration doc and codemods when feasible
• Error messages expose request ID and stable error codes from server contract

Anti-patterns

• Exposing raw HTTP response as the only return type for all operations
• Global mutable configuration changed implicitly on each call
• Retrying POST without idempotency key support
• Shipping generated code without a thin ergonomic facade
• Documenting endpoints that are not in the published spec

Handoff checklist

Before marking an SDK release ready:

• [ ] Spec revision ID recorded in SDK release notes
• [ ] Authentication documented with least-privilege scopes
• [ ] Default timeouts documented; retries documented as idempotent-only
• [ ] Pagination example in README for list operations
• [ ] Deprecation warnings for sunsetting API fields
• [ ] CI green: unit + contract (+ integration if credentials available)

SDK Testing and Documentation

Testing pyramid for SDKs

Contract tests

Goals

• Prove SDK builds requests the server expects (paths, headers, bodies)
• Prove SDK parses documented success and error responses

Practices

1. Pull official examples from OpenAPI examples or docs site 2. For each operation: golden file → expected HTTP wire dump 3. Run without network using mock transport recording exact bytes 4. Fail CI when spec revision changes without updating fixtures

OpenAPI tooling

• Validate spec with spectral or openapi-diff on PR
• Optional: generate tests from spec (openapi-generator test templates)
• Keep generated tests in contract/ directory separate from hand unit tests

Integration tests

• Use sandbox base URL and scoped API keys in CI secrets
• Rate-limit aware: serialize tests or use dedicated tenant
• Clean up created resources or use idempotent test names (test-{uuid})
• Skip integration job on fork PRs without secrets (document in CONTRIBUTING)

VCR / fixtures

• Record once; redact tokens and PII
• Pin cassette to spec version
• Re-record script documented in scripts/refresh-cassettes.sh only if team allows scripts

Mock server

• Prism or WireMock from OpenAPI for local dev
• Document make mock for contributors
• Do not rely on mock for behaviors undocumented in spec

Documentation alignment

SDK docs must mirror API reference sections:

Quickstart structure

1. Install package (copy-paste command per registry) 2. Obtain credentials (link to dashboard; env var names) 3. Minimal working call (list or get) 4. Next steps: pagination, error handling, webhooks (if applicable)

Examples directory

• examples/ runnable in CI (npm test runs example compile)
• One file per common task: create, list, delete, webhook verify
• No secrets in repo; use env vars

Reference documentation

• Auto-generate API reference from docstrings (JSDoc, Sphinx, godoc, javadoc)
• Publish to docs site with version selector matching SDK tags
• Cross-link to canonical HTTP API docs for field semantics

Style and consistency

• Align terminology with tech-writer-researcher style guides when org has one
• Use same error code strings as server (invalid_request, not InvalidRequest)
• Code samples tested in CI (markdown-exec or dedicated test runner)

Security in docs

• Never print live keys in README
• Document least-privilege scopes
• Warn against committing .env files; provide .env.example

Release documentation

Each release includes:

• Version number and date
• Added / changed / deprecated / removed (public API)
• Spec version or git SHA supported
• Migration notes for majors

Quality gates (pre-publish)

• [ ] Unit + contract tests green
• [ ] Linter + formatter applied per language
• [ ] CHANGELOG entry
• [ ] README quickstart verified manually or via smoke job
• [ ] No known CVEs in dependencies (audit job)
• [ ] Package size within budget (optional alert for JS bundles)

Handoff to build-validator

Before large SDK rewrites, optional review packet:

• Public API diff (semver impact)
• Breaking changes list
• Test coverage on contract fixtures
• Rollback plan (yank package version policy)

Metrics

Track:

• Time-to-first-successful-call (sandbox)
• Support tickets tagged sdk
• Download/version adoption curve
• Contract test failure rate on spec updates

Use metrics to prioritize ergonomic fixes over new surface area.

Versioning and Compatibility

Two axes

Document mapping: “SDK 2.x supports API v1 and v2; SDK 3.x drops API v1.”

Semantic versioning (SDK)

• MAJOR: breaking public API (removed method, renamed type, behavior change)
• MINOR: additive (new resource, optional field, new optional parameter)
• PATCH: bug fixes, internal retries, docs—no signature breaks

Pre-1.0 SDKs may use 0.y.z with explicit instability note.

API breaking change policy

Coordinate with API owners:

Deprecation in client code

1. Mark APIs @deprecated / docstring / annotation per language 2. Emit runtime warning on use (configurable warnings / logger) 3. Link replacement in warning message 4. Remove in next major with CHANGELOG entry

HTTP deprecation signals

Honor when present:

• Deprecation: true header
• Sunset header (RFC 8594)
• OpenAPI deprecated: true

Surface in release notes automation when spec scanned in CI.

Multi-language parity matrix

Maintain a table in SDK repo:

Parity rule: same semantics; release minors on staggered schedule acceptable with documented lag.

Codegen vs hand layer versioning

• Pin codegen to spec git SHA
• Tag generated code DO NOT EDIT
• Hand layer semver covers public exports only
• Regenerate on spec bump in dedicated PR for reviewability

Compatibility testing

• Test matrix: last N API versions in sandbox (or mock servers per version)
• Record minimum API version in SDK README
• Fail CI if spec introduces breaking change without major SDK bump label on PR

Release process

1. Update CHANGELOG (Keep a Changelog format) 2. Bump version in all package manifests 3. Run contract + integration tests 4. Publish to registries; tag git 5. Post migration guide for majors

Consumer migration guide template

## Upgrading from 1.x to 2.x

### Breaking changes
- `Client.create_user` renamed to `Client.users.create`
- `amount` now integer minor units (was decimal string)

### Steps
1. Bump dependency to `^2.0.0`
2. Replace ...
3. Run integration tests against sandbox

### Timeline
- API v1 sunset: 2026-12-01
- SDK 1.x support ends: 2026-09-01

Long-term support

Define policy:

• Support last two SDK majors with security patches
• Backport critical auth fixes to previous major when feasible
• No indefinite support for deprecated API versions

Anti-patterns

• Coupling SDK major bump to every server deploy
• Silent behavior change in patch release
• Removing deprecated APIs without sunset period documented on server
• Divergent error codes across languages for same server response