Unstable and undocumented endpoints

Stainless provides several options to handle unstable or undocumented endpoints in your SDKs. Use one or more of the approaches below depending on your circumstances and desired outcome.

Add beta or experimental endpoints in your SDKs

Unstable models and methods can be placed into a beta resource (or alpha, experimental, etc.).

For example:

openapi-spec.yaml

resources:
  beta:
    methods:
      create: /v2/create

When you’re ready to make unstable endpoints generally available (GA), move them out of the beta resource.

This approach works well in practice and provides the bex experience for end users. It’s easily discoverable, clearly documented, and adds a minimal amount of overhead.

Isolate unstable or undocumented endpoints in separate SDKs

To create a clear distinction between stable and unstable SDKs, create two OpenAPI specs: one with unstable endpoints and one without, then use the two specs to generate two sets of SDKs.

This approach keeps things completely separate, but it adds the overhead of managing two projects and repositories per language.

Keep unstable or undocumented endpoints out of your SDKs

Stainless SDKs have the ability to make raw API requests to undocumented or arbitrary endpoints. Each SDK’s readme file has general instructions for making these requests.

This approach keeps unstable and undocumented endpoints out of your SDKs entirely, but requires you to provide specific instructions to end users about using those endpoints with raw requests.