> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dema.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

> Dema GraphQL API versioning strategy and deprecation practices.

## 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.

<Info>
  The Dema API does not use versioned endpoints. All changes are made to the same endpoint while maintaining backward compatibility through deprecation practices.
</Info>

## 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**

```graphql theme={null}
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**

```graphql theme={null}
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:

```graphql theme={null}
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:

```graphql theme={null}
query AccountQuery {
  account {
    id
    name # Use this going forward
    legacyName  # Works during deprecation period
  }
}
```

<Warning>
  After the scheduled removal date, deprecated fields are permanently removed from the API. You must migrate to the new fields before the removal date.
</Warning>

## Checking for Deprecations

You can check for deprecated fields in the Dema API schema using GraphQL introspection:

```graphql theme={null}
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.

<Tip>
  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.
</Tip>

## 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