SDK documentation · Research synthesis
Which versions does your SDK code example actually support?
How Stripe, GitHub, Microsoft Graph and AWS separate SDK, API and runtime support, and what a useful compatibility record should tell readers.
A working SDK example depends on more than its package version. The runtime, remote API version, feature status and account setup can change what the same code does. We examined official policies and propose a compact compatibility record that separates what a provider supports, what a team tested and what a reader still needs to configure.
Key findings
SDK and API versions need separate fields. Stripe documents SDK-linked API defaults, while GitHub exposes an explicit REST version header. Neither should be inferred from a language-tab label. Stripe GitHub
An available package is not necessarily maintained. AWS distinguishes general availability, maintenance and end of support; Microsoft Graph documents different update coverage for its latest and preceding SDK majors. AWS Microsoft
A beta endpoint needs its own warning and setup instructions. Microsoft Graph does not support its beta APIs for production applications, and the way to select beta depends on the SDK. Microsoft
Our proposed record keeps provider policy, actual execution evidence and unchecked combinations separate. It is a documentation method, not a measured compatibility score.
How we researched this
This is a desk synthesis of nine primary sources inspected on November 17, 2026: official Stripe, GitHub, Microsoft Graph, AWS, Node.js and npm documentation, plus the Semantic Versioning specification. We selected policies that expose distinct compatibility boundaries, rather than a representative sample of SDKs. Two targeted research searches and a deeper synthesis informed discovery; the cited originals were independently opened and checked. We compared scope, defaults, support periods and exceptions. The record, review matrix and fictional example below are our proposed method. We did not install these SDKs, execute their samples or benchmark their reliability. Dates identify this source review, not the start of every policy.
What does a version label actually tell the reader?
Imagine a reader who copies an example, installs the named package and gets an error before the first useful result. A label saying JavaScript helps them choose a syntax. It does not tell them which runtime was used, which package release contains the method or which server behavior the request expects.
For documentation review, we recommend separating five questions. The table is an editorial checklist, not a claim that every SDK exposes all five controls.
| Question | What to record | What the label alone cannot establish |
|---|---|---|
| Can this environment run the code? | Language/runtime and relevant platform requirements | Whether the API account has the required capability |
| Which client interface is this? | Exact SDK package, release and imports | Which remote API version is selected |
| Which server contract is requested? | API version, endpoint family and selection mechanism | Whether this feature is stable or enabled |
| Is this feature intended for this use? | Stable, preview or beta scope and account prerequisites | Whether this particular example was executed |
| What was actually checked? | Test date, sample revision, environment and observed outcome | Compatibility with every untested combination |
The practical consequence is a change in how we write the introduction to a sample. An instruction to install the latest SDK leaves the reader to discover the relationship between the code and whatever package is current that day. A note identifying the package and API selection makes that relationship inspectable. It still needs a maintenance process behind it.
Keep the visible record short. Put the full dependency tree and execution log in the accompanying example project or review artifact. Readers should not have to parse a long manifest to find the installation command. They should be able to find the evidence when their environment differs.
This report focuses on those compatibility claims. For broader checks on correctness and useful assertions, see our research on testing API documentation.
What do Stripe, GitHub and Microsoft Graph do differently?
There is no universal rule that a newer SDK automatically selects the API version shown in a browser tab. The following policies illustrate why the selected server contract belongs next to the package information.
| Documented case | Boundary that matters | Information a sample should expose |
|---|---|---|
| Stripe server-side SDKs | Recent SDK releases select an associated API version | Package release and effective API version |
| GitHub REST | A request header selects a dated API contract | Explicit header value and applicable upgrade guide |
| Microsoft Graph | Stable and beta endpoints have different support expectations | Endpoint family, SDK-specific setup and beta warning |
Stripe describes its current server-side SDK releases as using the API version current when released; historical defaults and override support depend on the SDK. Its SDK support policy also separates major, minor and patch package changes. The package number and the API identifier therefore describe related but different things. SDK versioning
The details depend on the client. Stripe's version-selection guide says recent stripe-node package releases use their release-time API version, whereas stripe-node releases before v12 used the account default. It also explains that TypeScript types reflect the API version at SDK release. Java, Go and .NET guidance describes a fixed API version and warns that mismatched response types can cause failures. An instruction to override the version is consequently not a portable recipe for every language. API selection
GitHub recommends the X-GitHub-Api-Version header. At this review, its documentation lists 2022-11-28 as the default for requests without that header. It also says the unversioned default moves to the next oldest supported version when an older version is retired. The same page lists 2026-03-10 as a newer supported version. Supported does not mean selected by default. A missing selector is a dependency on that default. GitHub promises at least 24 months of support for the previous REST version after a new version is released. REST policy
Microsoft says many Graph SDKs default to v1.0. Accessing beta is language-dependent: its C# guidance uses a beta package, while the JavaScript client can select a version at client or request level. Graph beta APIs may change and are not supported for production applications. A tab switch that changes only the code language could conceal that more substantial difference. Beta guidance
Our recommendation is to review each language tab as its own entry point. Check its package, imports and endpoint choice together. Do not assume that translating method names preserves the same feature availability or support status.
Why can a sample still run after its support has ended?
Support is a promise about maintenance. Execution is an observation about a particular run. A useful documentation record keeps both, because one does not substitute for the other.
AWS says SDKs in maintenance receive critical bug and security fixes, but no new API updates or support for new regions. Its default maintenance duration is 12 months unless otherwise specified. After end of support, previously published releases remain available even though updates stop. AWS also reserves the right to end support for an underlying dependency without increasing the SDK major version. These are AWS policy boundaries, not universal package-manager rules. Maintenance policy
Microsoft Graph describes another distinction: its latest SDK major receives new features, fixes and workarounds; the immediately preceding major receives security fixes only for 12 months after the latest major's release. An example pinned to that preceding version might remain usable while already being outside the feature-update path. Support policy
Node.js recommends Active LTS or Maintenance LTS releases for production applications. That is a runtime lifecycle recommendation, not proof that a particular SDK supports every LTS release. The runtime and library policies need to be checked independently. Node.js releases
For a sample owner, the resulting decision has two parts. First, can readers reproduce the documented task in the stated environment? Second, is that environment still appropriate for the audience the page serves? A successful run can answer the first question without settling the second.
We recommend keeping older examples when they serve a real migration need, with an explicit scope and a link to the maintained path. Do not silently replace instructions inside a historical guide with incompatible new syntax. Equally, do not present an archived example as the default starting point merely because the download still works.
What should a sample compatibility record contain?
We propose a small record associated with a sample revision. It can live beside the example code and generate a concise note in the documentation. The schema below is a design proposal; the field names are not an industry standard.
| Field | Evidence or value to store | Reader-facing purpose |
|---|---|---|
| Sample identity | Stable sample name, source revision and relevant page | Ties the visible code to its reviewed source |
| Installation | Package names, tested releases, package manager and dependency record | Explains what was installed for the recorded run |
| Environment | Runtime, platform and required configuration | Makes environment differences visible |
| API selection | Endpoint family, selected contract and whether selection is explicit | Reveals a default that might otherwise be hidden |
| Feature scope | Stability label, required access and nonproduction restrictions | Prevents a preview feature from looking generally available |
| Observed result | Actual assertion, run time and link to evidence | Explains what tested means for this example |
| Ownership | Maintainer and conditions that trigger review | Gives future changes somewhere to go |
A missing field should remain visibly missing in the review process. If no integration run exists, record that. Do not fill the gap with the date of the latest prose edit. A spelling correction says nothing about the continued availability of a remote method.
Not every detail belongs in the first screen of the page. We would show the package, runtime, API selection and any important restriction before the copyable code. A nearby validation-details link can contain the exact revision, dependency file and assertions. This keeps the setup instructions together while making the evidence available for mismatch diagnosis.
Use different labels for different claims. Executed with describes an observation. Supported by the provider describes a policy with a source. Expected to work with describes an inference that needs a stated basis. A version range should not quietly change from the third category to the first because it looks cleaner in a table.
For a repository offering several examples, keep the identity stable even when the example moves to a new file. That lets an issue, a test result and a documentation page refer to the same task. Preserve enough history to explain why an old result no longer applies.
Should examples pin exact versions or accept a range?
The choice depends on the promise the example makes. A downloadable tutorial project benefits from a recorded dependency installation. A library integration guide may need to explain a supported range. Both still need a clear distinction between the range being claimed and the versions actually exercised.
For projects using the specification, Semantic Versioning requires a declared public API and assigns meaning to version changes against that API. Its rules treat 0.y.z releases as initial development, where the public API should not be considered stable. That makes the declared interface and the project's versioning policy relevant; a three-part number is not an independently verified compatibility result. SemVer specification
In the npm CLI 11 documentation, npm ci requires an existing lockfile, rejects a mismatch between the lock and package manifest, and does not rewrite either. npm also warns that dependency-tree options used to create the lock may need to be repeated during installation. This gives a concrete installation check, not evidence that the resulting client can complete a remote API task. npm ci
Our recommendation is to preserve a reproducible reference installation while separately checking candidate updates. This lets a maintainer investigate a regression against a known sample revision without turning yesterday's dependency set into a permanent recommendation.
A candidate update should retain its own result. If it fails, keep the failure associated with the candidate environment; do not erase the last valid result or label the whole product broken. If it passes, update the sample record and check the reader's installation instructions before changing the visible recommendation.
Ranges deserve similar care. A range may reflect a provider's stated support policy, a maintainer's commitment, or a test selection. Say which. Testing one release near the top of a range does not demonstrate every older release in it. Testing the endpoints does not prove all combinations in the middle either. The record should describe the coverage actually achieved and leave room for targeted checks when an important dependency changes.
How would this change a real documentation review?
Consider a fictional service called ParcelDesk with a guide titled Create a delivery. This is a worked editorial example, not an executed integration or a finding about a real vendor.
The page has Python and JavaScript tabs. Both show a client call and a sample delivery ID. A maintenance change updates the JavaScript package instruction, but the code is copied from an older revision. The page's updated date changes even though nobody runs the task.
Without a compatibility record, the reviewer has one vague question: does this example look current? With a record, the review becomes a sequence of specific questions:
- Does the installation instruction resolve the package release the example expects?
- Do the imports and method signature match that release's documented interface?
- Which API contract does the client select, explicitly or by default?
- Is the delivery feature enabled in the documented account environment?
- What result establishes that the operation completed, beyond receiving an HTTP response?
- Does the other language tab make the same promise, or does it need a separate scope?
Suppose the maintainer discovers that the JavaScript sample uses a preview-only method while the Python sample uses a stable operation. The repair is not to make the tabs look more alike. The guide needs to separate the preview task from the stable task, or clearly explain the difference before a reader chooses a language.
Now suppose installation and type checking pass, but no authorized test account is available. The honest result is narrower: installation and type checks passed; the remote operation was not exercised. The page should not acquire an integration-tested badge from that run.
If an integration check is later authorized, define the assertion before executing it. For the fictional delivery task, it might require retrieving the created test delivery and checking its expected state, then cleaning up the fixture where the service supports that. The specific action, resource ownership, potential charge and cleanup behavior must be understood first. This report does not run that test or recommend using customer resources as fixtures.
The outcome of the review is a better bounded promise. The reader sees which task the sample covers, which environment it used and where verification stops. That is more actionable than a recent date without an explanation of what changed.
What should trigger a new review?
A daily rewrite of every code block is unnecessary. A useful review process follows changes that could invalidate the record. The following matrix is our recommendation for triage, not a provider requirement or a guarantee that these checks catch every defect.
| Change detected | First question | Likely documentation action |
|---|---|---|
| SDK package update | Did the interface or selected API behavior change? | Review affected calls and validate the candidate installation |
| Runtime support change | Is the documented runtime still supported by both projects? | Update requirements or explain the legacy path |
| API default or retirement notice | Does the example rely on that default or contract? | Make selection explicit where supported and review migration steps |
| Feature becomes beta, stable or restricted | Does the sample's audience still have the documented access? | Correct the scope note and setup instructions |
| Reader reports a mismatch | Can the report be tied to an exact environment and sample revision? | Reproduce within an authorized test setup, then repair the relevant path |
| Prose-only edit | Did any executable instruction actually change? | Preserve the previous execution date rather than invent a fresh result |
Start with the highest-value task, not the largest possible version matrix. Identify the language and environment your guide explicitly recommends. Add coverage when you promise additional combinations or when a change creates a plausible compatibility boundary. Record untested combinations instead of turning them into green cells by assumption.
For a reader report, request the sample link, package version, runtime, explicit API selection and redacted error identifier. Avoid asking for credentials or complete account data. These details help distinguish an interface mismatch from a permission problem without requiring the reader to understand the whole SDK architecture.
A maintenance owner should also review the language of the claim. A sample can move from current starting point to legacy migration example without becoming useless. That change should be visible in the title or introduction and in links from the main quickstart. Keep the existing URL when it continues to serve a useful task.
For broader retirement communication, use a separate API migration and deprecation plan. For this narrower problem, the next step is straightforward: pick one SDK example and write down its package, runtime, API selection, feature scope and actual validation evidence. Any field you cannot fill is a concrete review task.
Limitations
The nine sources are a purposive selection of public policies, not a sample from which SDK failure rates can be estimated. Support rules can change, and a general policy may have language-specific or product-specific exceptions. We verified the cited statements against the originals on the stated date but did not run vendor samples, inspect customer environments or measure support-ticket reduction. Our compatibility record and fictional ParcelDesk review are proposals, not benchmark results. Provider support does not prove successful execution, and an execution result does not extend a provider support promise.
Sources
- How SDK versioning worksStripe · Accessed 2026-11-17
- Set a Stripe API versionStripe · Accessed 2026-11-17
- API VersionsGitHub · Accessed 2026-11-17
- Use the Microsoft Graph SDKs with the beta APIMicrosoft · Accessed 2026-11-17
- Versioning, support, and breaking change policies for Microsoft GraphMicrosoft · Accessed 2026-11-17
- Node.js ReleasesNode.js · Accessed 2026-11-17
- AWS SDKs and Tools maintenance policyAmazon Web Services · Accessed 2026-11-17
- Semantic Versioning 2.0.0Semantic Versioning · Accessed 2026-11-17
- npm ci, CLI version 11 documentationnpm · Accessed 2026-11-17