Skip to main content

Frequently Asked Questions (FAQs)

How are generated SDKs tested?​

We generate the following:

  • A set of unit tests for the core client

  • For each endpoint configured in your Stainless config file, we generate a set of test cases — sending a synchronous request with only required params, sending a synchronous with all params, and the same for asynchronous requests. We are using Prism to emulate your API based on your OpenAPI spec file.

Tests and linters are executed automatically in CI for any change to the SDK. You can also run them locally by running ./scripts/test in a terminal from the root of of the SDK repository, the script will setup everything it needs and execute all tests.

In addition, we recommend that users add examples to the directory ./examples of the generated SDK. This directory is safe to use as you wish, Stainless won’t overwrite its content. That simplifies testing uses cases against your live API.

Here is a concrete example: https://github.com/openai/openai-node/blob/master/examples/demo.ts

What if my API define endpoints that aren't stable yet?​

Here are our recommended approaches:

Option 1 — Use a Beta Resource​

Unstable models and methods can be placed into a beta resource (or alpha, experimental). When they are ready to be generally available (GA), you can move them out of the beta resource. This approach has worked well in practice and results in the best Developer Experience (DX) for end users — it is easily discoverable, is clearly documented, and adds a minimal amount of overhead.

Option 2 — Create and Release a Separate SDK​

Another option is to create and release a separate SDK for the second spec. This can create a clear distinction between the stable SDK and the non-stable one. However, it may be more confusing for end-users and adds the overhead of managing two projects/repos per language.

Option 3 — Access Undocumented Endpoints​

You can choose not to configure endpoints that aren't stable, and instead access them as undocumented endpoints. This method is documented in the generated READMEs for each language, providing a way to make custom/undocumented requests.

How can I migrate an endpoint to a new version?​

If you're replacing an endpoint with a new version, you can use aliases to point to the new version. This way, users will still see the same method name in the SDK, but it will point to the new version. This can make the process of upgrading and deprecating methods easier for you and your users.

Let's assume you start with a method POST /data/create that you configured in your Stainless config like so:

resources:
  users:
    methods:
      create: /data/create

To migrate this method, add the following:

  • a new version of the endpoint, let's call it createV2
  • Rename the existing method to createV1
  • Add an alias to the method createV2 to target the version you want users to use by default
  • Optionally, add a deprecation message to the old method
resources:
  users:
    methods:
      createV1:
        endpoint: /data/create
        deprecated:
          go: use `List` instead
          default: use `list` instead
      createV2: /data/createV2
      create:
        type: alias
        to: createV2

Importantly, make sure to release this as part of a major version bump with migration instructions. Check out our publishing guide for more information.

Our API spec is made of multiple OpenAPI files but Stainless only support a single file. What can we do?​

We recommend using the redocly CLI to combine OpenAPI files. Redocly wrote this comprehensive blog article with clear examples.

If you're using Stainless Github Action to upload your spec file, just add an extra step beforehand to run the redocly CLI and combine your files in a single spec file.

We are using Postman collections, how can we get an OpenAPI file?​

Postman does offer an API to transform a collection to OpenAPI, documented here.

In addition they wrote an excellent blog article on the subject with simple examples. We recommend giving it a read!

How does Stainless handle dependency security?​

We take dependency security very seriously. We have systems and processes in place to scan, be alerted to, and update dependencies for all SDKs we generate. We seriously review alert reports and their associated CVEs and take rapid actions when necessary.

Automated Dependency Scanning​

We have an automated system set up performing dependency scanning. This system alerts us to any vulnerabilities identified in our dependencies.

Rapid Updates​

When a vulnerability is detected, we can quickly push an update to our codegen system to address the issue the next time a build is triggered. Dependency updates rely on the same release and versioning flow used for OpenAPI and Stainless config changes.

This ensures that the SDKs remain secure and up-to-date, as long as release PRs opened by Stainless are regularly merged.

We strongly recommend that you automate your OpenAPI updates, that way your SDKs are built regularly without any manual action on your part.

Patch via custom code​

While our systems will handle most cases, you may have the need to quickly address a vulnerability by yourself. In that situation you can always directly open a PR on your SDK repository, and merge it yourself. See our Patch with custom code docs for more details.

I think I found a security issue, how do I report it? Do you have a security policy?​

Stainless takes security seriously, you are encouraged to report any security vulnerability promptly so that appropriate action can be taken.

Reporting an SDK security issue​

Please contact the Stainless team at security@stainlessapi.com with detailed information. We will review and respond promptly.

For example:

Please contact the Stainless team at security@stainlessapi.com with detailed information. We will review and respond promptly.

If you encounter security issues that are not directly related to SDKs generated by Stainless but pertain to the services or products provided by the company who owns and publish the SDK, please follow the respective company's security reporting guidelines.

See the file SECURITY.md present in SDKs generated by Stainless for details.

Responsible Disclosure​

We appreciate the efforts of security researchers and individuals who help us maintain the security of SDKs we generate. If you believe you have found a security vulnerability, please adhere to responsible disclosure practices by allowing us a reasonable amount of time to investigate and address the issue before making any information public.

Thank you for helping us keep the SDKs and systems they interact with secure.