Versioning and changelog

Versioning policy

We aim for stable, predictable changes. The API follows a conservative approach to breaking changes and a clear deprecation process.

What is considered breaking

• Removing a type, field or argument

• Changing a field’s type or nullability

• Changing the behaviour or meaning of an existing field

• Removing enum values or reusing them with different meaning

What is considered non-breaking

• Adding new types, queries or mutations

• Adding nullable fields or arguments with safe defaults

• Adding enum values where clients are expected to handle unknown values

Deprecations

• Deprecated items are marked with the GraphQL directive @deprecated and a reason

• A deprecation window of [eg. 90 days] is provided before removal [confirm window]

• We publish migration notes and examples for each deprecation

Example

type Response {
  sentiment: String @deprecated(reason: "Use insights.sentimentScore")
  insights: Insights
}

Release cadence and support windows

• Regular releases: weekly or bi-weekly batches for non-breaking updates

• Breaking changes: grouped and announced well in advance with migration guides

• Support window: the previous schema version remains supported for [eg. 90 days] after a breaking release

Changelog format

Each entry includes date, type and details. Types: Added, Changed, Deprecated, Removed, Fixed, Security.

Sample entries

2025-09-08 — Added
Added field project.status to help filter active and archived projects

2025-09-02 — Changed
Raised default page size limit for responses to 200; rate limits unchanged

2025-08-26 — Deprecated
Deprecated Response.sentiment in favour of Insights.sentimentScore

2025-08-19 — Fixed
Resolved occasional 404 on media download when signed URL was near expiry

2025-08-12 — Security
Rotated signing keys for media links; no customer action required

Migration guidance template

1. Identify deprecated fields in your queries via schema introspection or error logs

2. Replace deprecated fields with suggested alternatives

3. Validate pagination and filters still match your use case

4. Roll out behind a feature flag and monitor errors

Before

query Responses($id: ID!, $first: Int) {
  project(id: $id) {
    responses(first: $first) {
      edges { node { id sentiment } }
    }
  }
}

After

query Responses($id: ID!, $first: Int) {
  project(id: $id) {
    responses(first: $first) {
      edges { node { id insights { sentimentScore } } }
    }
  }
}