GrowSurf REST API versioning and deprecation policy

Versioning

The REST API is versioned in the URL path:

https://api.growsurf.com/v2

GrowSurf can add backward-compatible functionality inside an existing version — new endpoints, new optional request fields, new response fields — so ignore response fields you do not use. A breaking contract change requires a new version.

Minimum notice

GrowSurf gives at least 12 calendar months of public notice before a planned breaking removal. The clock starts when GrowSurf marks the affected surface as deprecated in the public OpenAPI schema and publishes migration guidance. The removal date cannot fall earlier than the same calendar date 12 months later.

How a deprecation is signalled

• The OpenAPI operation, parameter, or schema field carries deprecated: true.
• Responses from the affected resource carry an RFC 9745 Deprecation field with the deprecation timestamp.
• Once a removal date is set, responses also carry an RFC 8594 Sunset field with that date.
• The documentation names the replacement, the migration steps, and any compatibility differences.

Every REST response — deprecated or not — carries a link back to this policy, so you can find it without a successful call:

Link: <policy-url>; rel="deprecation"

No Deprecation field means the surface is not deprecated.

What to do as a client

• Check the GrowSurf OpenAPI spec during development and before you update a dependency.
• Treat Deprecation as a migration signal.
• If a response also carries Sunset, finish the migration before that date.

If a published migration path does not cover your integration, contact GrowSurf Support.