Skip to main content

​
Overview

The Dema GraphQL API follows a continuous evolution approach rather than traditional API versioning. We evolve the schema incrementally using additive changes and deprecation, avoiding breaking changes whenever possible.
The Dema API does not use versioned endpoints. All changes are made to the same endpoint while maintaining backward compatibility through deprecation practices.

​
Our Versioning Approach

The Dema API evolves continuously without version bumps. We make changes by:
  • Adding new fields or types without modifying existing ones
  • Adding new enum values to existing enums
  • Deprecating fields instead of removing them immediately
  • Maintaining backward compatibility so your existing queries continue to work
Most API changes are deployed without requiring version updates from your side.

​
Changes That Don’t Require Versioning

The following changes are non-breaking and will be deployed without version updates:
  • Adding new fields or types
  • Adding new enum values
  • Making a non-null field nullable (widening the type)
  • Any additive changes that don’t alter existing field signatures
Example: Adding a new field 
type Account {
  id: ID!
  name: String!
  email: String  # New field added - your existing queries continue to work
}

​
Changes That Require Deprecation

When we need to make breaking changes, we use deprecation with a migration period. Breaking changes include:
  • Changing field names or types - We deprecate the old field and add the new one
  • Removing fields - Fields are always deprecated before removal
  • Changing nullability - Making a nullable field non-null requires deprecation
  • Changing argument types - Breaking argument changes go through deprecation
Example: Field rename with deprecation 
type Account {
  id: ID!
  legacyName: String!
    @deprecated(reason: "Deprecated: use `name` instead. Scheduled for removal on 2026-06-30.")
  name: String!
}

​
Deprecation Policy

When we need to remove or replace a field, we follow this deprecation process:

​
Deprecation Timeline

We maintain deprecated fields for 90 days before removal. This gives you time to migrate to the new field or structure.

​
Deprecation Reason Format

All deprecated fields in the Dema API use this standardized format: 
"Deprecated: use `<newField>` instead. Scheduled for removal on <YYYY-MM-DD>."
Every deprecation includes:
  • The replacement field or approach to use
  • The exact removal date in YYYY-MM-DD format
  • Clear guidance on how to migrate

​
Example: Deprecation in Practice

When we deprecate a field, both the old and new fields are available during the 90-day period: 
type Account {
  id: ID!
  name: String!
  legacyName: String
    @deprecated(reason: "Deprecated: use `name` instead. Scheduled for removal on 2026-06-30.")
}
During the deprecation period, you can query either field: 
query AccountQuery {
  account {
    id
    name # Use this going forward
    legacyName  # Works during deprecation period
  }
}
After the scheduled removal date, deprecated fields are permanently removed from the API. You must migrate to the new fields before the removal date.

​
Checking for Deprecations

You can check for deprecated fields in the Dema API schema using GraphQL introspection: 
query CheckDeprecations {
  __type(name: "Account") {
    fields {
      name
      isDeprecated
      deprecationReason
    }
  }
}
This query returns all fields for a type, including which ones are deprecated and their removal dates. You can also use a GraphQL client to check for deprecated fields.
All API changes and deprecations will be communicated through relevant mediums. We recommend migrating to new fields as soon as they become available to avoid disruption when deprecated fields are removed.

​
Best Practices for API Consumers

  • Monitor deprecations: Use introspection to check for deprecated fields in your queries
  • Migrate early: Start using new fields as soon as they’re available
  • Test thoroughly: Verify your application works with new fields before the removal date