Skip to main content

Get started with Stainless SDKs

Great SDKs for your API drive faster integration, broader feature adoption, quicker upgrades, and trust in your engineering quality. At Stainless, we work hard to make each SDK feel as though it were hand-written by an expert in the language who had the time to get it right.

In just 15 minutes, you have SDKs that are consistent with your API specification and can be shipped as a beta to your users. You can iterate from there, polishing and shaping the SDKs to faithfully represent your brand.

Upload your OpenAPI spec​

Stainless SDKs are generated from an OpenAPI spec and a Stainless config which tells the generator how to interpret the OpenAPI.

The OpenAPI spec is a standard way of describing your API. Stainless reads and translates your OpenAPI spec into world-class SDKs that your users love.

tip

Your spec does not need to be perfect to try out Stainless. You can always polish and improve your spec later, then regenerate your SDKs.

If you don’t yet have an OpenAPI spec, you can create an OpenAPI spec or just get started quickly with an example spec.

Creating a Stainless project

Sign up on the Stainless dashboard, then create a project by uploading your OpenAPI spec.

We generate a first draft of the Stainless config for you and use that to generate preview staging SDKs in less than a minute.

Trying your SDKs

Once the SDKs are done generating, inspect the structure of the SDKs with a preview of your SDK reference docs. You can click on a method to see a snippet of how to use that method with your new SDKs.

You should also try making requests with your new SDKs.

  • If you want to get started quickly, you can use GitHub codespaces with the dev containers we generate for you in the SDK repository.
  • If you want to try it on your machine, you can do so by following the instructions in CONTRIBUTING.md. On our first generation, we generate an example for you in the repository such as acme-node/examples/demo.ts which you can extend or copy off of.
Sharing your SDKs

Take a moment to click on the Members tab in your Stainless project page to add additional team members. After accepting an email invite and authenticating with their GitHub handle, members are automatically added to Stainless project and the staging GitHub repositories we generate for you.

Iterate on your SDKs​

Well-structured SDKs help developers understand your API. Ensure the organization and naming represents your API and aligns with how your developers use it.

You primarily make changes by editing the Stainless config. The Stainless config is stored in the cloud and can be either edited manually, in the web-based SDK Studio, or via the API.

Resolving diagnostics

The Stainless generator always attempts to output something, even if it isn't perfect.

When the generator detects that there are issues with the OpenAPI spec or the Stainless config, the generator raises diagnostics:

  • Error: Indicates issues with the usability of the SDK, such as not being able to compile the library or not successfully make a request.
  • Warning: Indicates major issues with the user experience of the SDK, but doesn't affect usability of the rest of the SDK, such as an invalid schema or a misconfigured endpoint.
  • Note: Indicates potential issues with the user experience of the SDK, but not too consequential for the user.

For a successful demo, you should resolve at least all the Error diagnostics, and aim to resolve all diagnostics by a 1.0.

Configuring structure

The best structure for an SDK is the one that is consistent with the rest of your communications with the user and is highly dependent on the shape of your API.

Stainless is built with this reality in mind. The generator offers extensive configuration to organize the functionality in your API around RESTful objects, which we call resources. We suggest you decide on a comprehensive resource structure and configure from there.

Publish an alpha​

Once all diagnostics errors are resolved, you are ready to publish an alpha version of the SDK. 🚀

The Publish your SDKs guide goes into detail about how to link a production repo, configure package managers, and how to manage versions.

Even if you aren't yet ready to release the SDKs to your users, we recommend publishing alphas and betas as soon as possible. Publishing now will make it easier to share and test internally and make the transition to a full 1.0 release seamless.

Polish for 1.0​

Now that you have a solid starting point for your SDKs, here are the next steps:

  1. Resolve or acknowledge all diagnostics in the SDK Studio.
  2. Automate updates so your SDKs change in lockstep with your API.
  3. Patch with custom code to add bespoke functionality.
  4. Integrate with docs frameworks to add documentation.