SDK Overview Template

SDK Overview: [Product name] SDKs

Landing page for the official client libraries of an API: which languages are supported and at what status, how to install each SDK, configure authentication, make a first call, handle errors, retries, timeouts and pagination, turn on logging, and which versioning and support policy applies, with links to the generated reference for each language. It assumes the API is described with the OpenAPI Specification 3.2.1 (3.1.x also widely used) and that SDK releases follow Semantic Versioning 2.0.0. Replace every [bracketed] value and every row marked Example.

Document control

Approvals

Revision history

Contents

1. About the SDKs
2. Supported languages
3. Install
4. Authentication and configuration
5. Make your first call
6. Handle errors
7. Retries and timeouts
8. Pagination
9. Logging and debugging
10. Webhooks and events
11. Versioning and support policy
12. Reference and resources
13. Glossary and references

1. About the SDKs

The [Product name] SDKs are official client libraries for the [API name]. They handle authentication, request signing, serialisation, retries with backoff, pagination and typed errors, so that your code deals with orders and customers rather than with HTTP details.

Example: The SDKs are generated from the public OpenAPI 3.2.1 description of the Orders API and then extended with handwritten helpers for pagination, retries and webhook signature checks. Generated code and helpers ship together in one package per language. Because the method names come from the operationId values in the description, a renamed operation is a breaking change for SDK users; the API Changelog (docs/api-changelog) flags such changes.

You can always call the HTTP API directly. Every SDK feature described here maps to documented API behaviour, so the API Overview (docs/api-overview) and the API Reference (dev/api-reference) remain the contract.

2. Supported languages

Runtime minimums in this table are examples. Set yours from the support schedule that each runtime publishes, and review the table when a runtime version reaches its upstream end of life.

Example: The bracketed minimums were all supported upstream when this template was checked on 2026-10-24 (endoflife.date and the vendors' own pages): Python 3.11 until 2027-10-31, Node.js 22 LTS until 2027-04-30, Java 17 (Eclipse Temurin builds) until at least 2027-10-31, Go 1.26 until two newer Go major releases ship, and .NET 10 LTS until 2028-11-14. Node.js 20 (2026-04-30), Python 3.10 (October 2026) and Go 1.24 had already reached end of life, and .NET 8 ends on 2026-11-10, which is why they are not used. Node.js 22, Python 3.11 and Java 17 reach end of life during 2027, so plan when the SDKs drop them under section 11.3.

2.1 Status values

2.2 Feature coverage

3. Install

Install the SDK with your language's package manager and pin the major version, so that a new major release never arrives without a code change.

# Python
pip install "corvid-commerce>=5.3,<6"

# TypeScript and JavaScript
npm install @corvid/commerce@^5.3.0

# Go
go get corvid.example/commerce/v5@v5.3.0

# .NET
dotnet add package Corvid.Commerce --version 5.3.0-beta.2

<!-- Java (Maven) -->
<dependency>
  <groupId>com.corvid</groupId>
  <artifactId>commerce</artifactId>
  <version>5.3.0</version>
</dependency>

Verify what you install. Example: Every release is published from CI with a provenance attestation, and a software bill of materials is attached to each release on the source repository. Check them in your supply chain tooling before you upgrade.

Dependencies. Keep the SDK's own dependencies small. List any that a reader may need to know about, such as an HTTP client that conflicts with a common framework version. Example: The Python SDK depends on one HTTP library and one typing helper; the Go SDK uses the standard library only.

4. Authentication and configuration

4.1 Credentials

Example: The Orders API uses secret API keys for server-side code and OAuth 2.0 client credentials for partner apps. The SDKs read the key from the environment variable CORVID_API_KEY when you do not pass one explicitly.

Never put a secret key in source code, a mobile app, a browser bundle or a public repository. Load it from a secrets manager or the environment at runtime, give each environment its own key, and rotate keys on a schedule and whenever someone with access leaves. If a key is exposed, revoke it in the dashboard first and investigate afterwards.

4.2 Configuration options

Precedence. Example: A value passed in code wins over an environment variable, which wins over the default. State this order explicitly, because readers debugging a wrong endpoint need to know where the value came from.

Telemetry. If an SDK can report anything about its own use, keep it off by default, report aggregate counts only (SDK version, runtime version, operation name), never send request or response content, credentials or personal data, and document how to confirm that it is off.

4.3 Create a client

# Python
import os
from corvid_commerce import Client

client = Client(api_key=os.environ["CORVID_API_KEY"])

// TypeScript
import { Client } from "@corvid/commerce";

const client = new Client({ apiKey: process.env.CORVID_API_KEY });

// Go
client := commerce.NewClient(commerce.WithAPIKey(os.Getenv("CORVID_API_KEY")))

Create one client per process and reuse it. The client holds a connection pool; creating a client per request wastes connections and slows every call.

5. Make your first call

Use a sandbox key for this step. The sandbox starts with sample orders, so the call returns data straight away.

# Python: list the five most recent orders
for order in client.orders.list(limit=5):
    print(order.id, order.status, order.total_amount.value, order.total_amount.currency)

// TypeScript: list the five most recent orders
for await (const order of client.orders.list({ limit: 5 })) {
  console.log(order.id, order.status, order.totalAmount.value, order.totalAmount.currency);
}

// Java: list the five most recent orders
for (Order order : client.orders().list(ListOrdersParams.builder().limit(5).build())) {
    System.out.println(order.getId() + " " + order.getStatus());
}

Expected output (Example, sandbox data):

ord_9f3k2 paid 120.00 EUR
ord_9f3k1 partially_shipped 48.50 EUR
ord_9f3jz shipped 15.99 EUR

If you see an authentication error, check that you used a sandbox key with the sandbox base URL. Mixing a sandbox key with the production URL is the most common first-call failure.

Next steps. Create an order with an idempotency key, then subscribe to the order.updated event type (AsyncAPI operation orderUpdated). The Quickstart (docs/quickstart) walks through both.

6. Handle errors

Every SDK maps API errors to typed errors with the same fields: the HTTP status, the API error code, a human-readable message and the request ID. Log the request ID; support needs it to trace a call.

from corvid_commerce import errors

try:
    order = client.orders.create(lines=[...], idempotency_key=key)
except errors.ValidationError as e:
    for field_error in e.field_errors:
        print(field_error.field, field_error.message)
except errors.ApiError as e:
    log.error("Orders API error %s (request %s)", e.code, e.request_id)
    raise

Do not parse error messages; they can change. Branch on the error type and the error code, which are part of the contract.

7. Retries and timeouts

7.1 Retries

Example: The SDKs retry a failed request up to 2 times after the first attempt when the failure is a connection error, a timeout, 429 or a 5xx status. They wait with exponential backoff and random jitter, and they honour the Retry-After header when the API sends one.

The SDKs retry a write only when it is safe: GET, PUT and DELETE are idempotent by definition, and POST is retried only when the request carries an idempotency key. The SDKs add a key automatically to POST calls when you do not supply one, and reuse it on every retry of that call. Supply your own key when you might repeat the whole operation later, for example after a process restart.

# Override retries for one call
client.orders.list(limit=100, max_retries=5)

# Turn off retries for a client
client = Client(api_key=key, max_retries=0)

7.2 Timeouts

Set timeouts shorter than the deadline of the code that calls the SDK. A web request that must answer in 10 seconds cannot wait 90 seconds for a retried API call; pass a shorter timeout or use the language's cancellation mechanism (context in Go, AbortSignal in TypeScript).

8. Pagination

Example: List operations return pages of up to 100 items with a cursor for the next page. The SDK list methods return an iterator that fetches the next page only when you reach the end of the current one, so you can process large result sets with constant memory.

# Automatic: iterate every order updated since a timestamp
for order in client.orders.list(updated_since="2026-10-01T00:00:00Z"):
    process(order)

# Manual: one page at a time, for example to checkpoint the cursor
page = client.orders.list_page(limit=100)
while page:
    save_checkpoint(page.next_cursor)
    handle(page.items)
    page = page.next_page()

// Go: automatic iteration
iter := client.Orders.List(ctx, &commerce.ListOrdersParams{Limit: 100})
for iter.Next() {
    process(iter.Current())
}
if err := iter.Err(); err != nil {
    return err
}

Store the cursor, not a page number, if you resume a long synchronisation later. Cursors stay valid while new orders are created, and they expire after [24 hours] (Example). For incremental synchronisation, filter by update time instead of listing everything again.

9. Logging and debugging

The SDKs log through the standard logging facility of each language, so SDK messages appear in your existing log pipeline.

Redaction. Example: At every level, the SDK replaces the Authorization header, API keys, webhook secrets and fields marked as sensitive in the OpenAPI document (such as email, phone and address) with [REDACTED]. Use debug only in development or for a short, controlled investigation, and never forward debug logs to third parties.

Request IDs. Every response carries a request ID (Example: header X-Request-Id), and every SDK error exposes it. Include it when you contact support.

Deprecation warnings. When the API returns a Deprecation header (RFC 9745) or a Sunset header (RFC 8594), the SDK logs one warning per operation per process with the dates and the documentation link. Treat these warnings as work items; the Deprecation Notice (docs/deprecation-notice) explains what to do.

# Turn on info logging for one run
CORVID_LOG=info python sync_orders.py

10. Webhooks and events

Example: The SDKs include a helper that verifies the signature of a webhook delivery and returns a typed event. Verify against the raw request body bytes and the signature header, with the endpoint secret from your dashboard. The helper rejects deliveries whose timestamp is older than five minutes, to limit replay.

// TypeScript (framework-neutral)
const event = client.webhooks.constructEvent(rawBody, signatureHeader, endpointSecret);
if (event.type === "order.updated") {
  await handleOrderUpdate(event.data);
}

Respond with a 2xx status quickly and do the work asynchronously; deliveries that time out are retried and can arrive more than once, so make your handler idempotent by event ID. For the delivery model, see the Webhook Delivery system design (system-design/design-webhook-delivery).

11. Versioning and support policy

11.1 Version numbers

The SDKs follow Semantic Versioning 2.0.0:

• Major (for example 5.0.0): breaking changes to the SDK interface, a new default API version, or removal of a supported runtime version.
• Minor (for example 5.3.0): new API operations and fields, new helpers, and deprecations of SDK methods.
• Patch (for example 5.3.1): fixes that do not change the interface.

Example: SDK major 5 targets Orders API v2; SDK major 4 targets v1. An SDK minor release never changes the API version it sends by default.

11.2 Support windows

11.3 Runtime support

Example: An SDK supports every runtime version that is supported upstream when the SDK major version is released. When a runtime version reaches its upstream end of life, the next SDK minor release may stop testing against it, and the next SDK major release removes it. Removal is announced in the API Changelog (docs/api-changelog) at least [90 days] ahead.

11.4 Upgrading

Read the SDK release notes for every major version you cross. Upgrade one major version at a time in a branch, run your tests against the sandbox, and watch for deprecation warnings in section 9 before you deploy. The Migration Guide (docs/migration-guide) covers API-level changes; each SDK repository carries an upgrade guide for SDK-level changes.

12. Reference and resources

Other resources:

• API Reference (dev/api-reference) and the OpenAPI description document, the source of truth for operations and fields.
• API Changelog (docs/api-changelog) for API-level changes and the SDK versions that include them.
• Known Issues (docs/known-issues) for open problems and workarounds.
• Troubleshooting (docs/troubleshooting) for common errors.
• Support: [support channel], [community forum], [status page].

Reporting a bug. Open an issue in the SDK repository with the SDK version, runtime version, a minimal code sample and the request ID. Remove keys and personal data before you post. Report security issues privately as described in the repository security policy.

13. Glossary and references

13.1 Glossary

13.2 References

Standard and licence note

Based on the OpenAPI Specification 3.2.1 (OpenAPI Initiative, https://spec.openapis.org/oas/v3.2.1.html, Apache License 2.0) as the source for generated clients, on Semantic Versioning 2.0.0 for version numbers, and on IETF RFC 9745, RFC 8594 and RFC 9110 for deprecation signals, retries and status codes. The section list was informed by the sdk-overview template of The Good Docs Project (MIT-0); no text from it is reused. Corvid Commerce, its package names, versions and code samples are fictional. This template is original text written for this collection. Check the current specification versions and each runtime's own support schedule before use. Template licence: MIT.