API Lifecycle Guide

Lifecycle stages

Beta

A Beta endpoint is available in the UAT (sandbox) environment for integration testing. Beta endpoints are not available in production.

A beta endpoint is identified by the beta tag in the API reference.

What to expect during beta:

• The endpoint is functional and testable in UAT
• Request and response schemas may change before GA
• There is no committed timeline for GA promotion

Recommendations:

• Do not release beta-dependent features to end customers in production
• Monitor the changelog for updates to beta endpoints
• Treat any schema changes during beta as expected, not breaking

General Availability (GA)

A GA endpoint has had its beta tag removed and is available in both UAT and production environments.

GA endpoints are covered by DriveWealth's API stability guarantees. Any breaking changes to a GA endpoint will follow the deprecation process described below.

What you can rely on with GA endpoints:

• The endpoint is stable and production-ready
• Schema changes will be additive and non-breaking (see Breaking vs. non-breaking changes)
• Advance notice will be given before any breaking changes
• The endpoint appears in the changelog when it graduates from beta

Deprecated

A Deprecated endpoint is marked with a deprecated tag in the API reference. It remains available in both UAT and production but should not be used for new integrations.

Deprecated endpoints have a defined sunset date after which they will be removed entirely.

What to expect when an endpoint is deprecated:

• A deprecation notice is published in the changelog
• The sunset date is stated in the deprecation notice — typically a minimum of 12 months from the deprecation date
• The endpoint continues to function until the sunset date
• DriveWealth will communicate migration guidance alongside the deprecation notice

Recommendations:

• Begin planning your migration as soon as you see a deprecation notice
• Do not build new features on deprecated endpoints
• Contact your DriveWealth integration manager if the timeline creates a problem for your roadmap

Retired

A retired endpoint has been fully removed. Requests to a sunset endpoint will return a 410 Gone response.

{
  "error": {
    "code": "ENDPOINT_REMOVED",
    "message": "This endpoint was removed on 2025-06-01. See https://developer.drivewealth.com/apis/changelog for migration guidance."
  }
}

Lifecycle at a glance

Breaking vs. non-breaking changes

DriveWealth distinguishes between changes that require action on your part and changes that are safe to absorb automatically.

Breaking changes

A breaking change is any modification that can cause an existing, correctly-written integration to fail or behave incorrectly without code changes on your side.

DriveWealth will never introduce breaking changes to a GA endpoint without first deprecating it and providing a migration path.

Breaking changes include:

• Removing an endpoint entirely
• Removing a required or optional request field
• Removing a response field
• Renaming a field
• Changing a field's data type (e.g. string → integer)
• Changing a field's format in a meaningful way (e.g. date format YYYY-MM-DD → Unix timestamp)
• Changing an HTTP method (e.g. POST → PUT)
• Changing a URL path or path parameter
• Adding a new required request field
• Changing authentication requirements
• Narrowing the range of accepted values for a field (e.g. reducing the max length of a string)
• Removing or renaming an enum value that appears in responses

Non-breaking changes

A non-breaking change can be introduced to GA endpoints at any time without a deprecation cycle. Well-written integrations should absorb these changes gracefully.

Non-breaking changes include:

• Adding a new optional request field
• Adding a new response field
• Adding a new endpoint
• Adding a new enum value to a request field (see note below)
• Relaxing validation (e.g. increasing the max length of a string)
• Changing the order of fields in a JSON response
• Adding new error codes to the documented error set
• Performance improvements with no observable behavior change

Note on new enum values in responses: If your integration deserializes responses into a strict enum type, a new response enum value can cause a runtime error. DriveWealth recommends using permissive deserialization for enum fields and treating unknown values as a signal to check the changelog — not as a hard failure.

How to write a resilient integration

Following these practices will ensure your integration handles non-breaking changes without requiring code changes:

• Ignore unknown fields. Do not reject responses that contain fields your code does not recognize.
• Use permissive enum handling. Log and skip unknown enum values rather than throwing an error.
• Do not rely on field ordering. JSON object field order is not guaranteed.
• Check for null explicitly. Do not assume that a field present today will always have a non-null value.

How changes are communicated