Migrate an endpoint to a new version

If you’re replacing an endpoint with a new version, 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 makes 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.