# API Versioning

https://api-docs.lumar.io/docs/graphql/versioning

The Lumar GraphQL API uses a single evolving schema rather than numbered API versions. This means the API endpoint stays the same, and changes are made in a backward-compatible way whenever possible.

## Single evolving schema

Instead of maintaining multiple API versions (e.g., `/v1`, `/v2`), Lumar extends the existing schema by:

- **Adding** new types, fields, queries, and mutations without breaking existing queries.
- **Deprecating** fields that will be removed in the future, giving you time to migrate.

Your existing queries will continue to work as new fields are added alongside them.

## How deprecations work

When a field is scheduled for removal, it is marked with a `@deprecated` directive in the schema. The directive includes a `reason` that typically points you to the replacement.

For example, the `datasourceCode` field on `ReportTemplate` was deprecated in favour of `datasourceCodeEnum`:

```graphql
query GetReportTemplateWithDatasource {
  getReportTemplates(first: 1) {
    nodes {
      code
      name
      datasourceCodeEnum
    }
  }
}
```

**Response:**
```json
{
  "data": {
    "getReportTemplates": {
      "nodes": [
        {
          "code": "all_pages",
          "name": "All Pages",
          "datasourceCodeEnum": "CrawlUrls"
        }
      ]
    }
  }
}
```

In this example, you should use `datasourceCodeEnum` (which returns a proper `DatasourceCode` enum) instead of the deprecated `datasourceCode` string field.

### Identifying deprecated fields

- **Schema introspection** -- deprecated fields include an `isDeprecated: true` flag and a `deprecationReason` string in introspection results.
- **GraphQL clients** -- most clients and IDEs (such as Altair or GraphQL Playground) visually mark deprecated fields with a strikethrough.
- **Schema documentation** -- the [schema reference](/docs/schema.md) indicates deprecated fields.

## Checking the API

You can verify your connection to the API by running a simple query:

```graphql
query GetApiVersion {
  me {
    id
    username
  }
}
```

**Response:**
```json
{
  "data": {
    "me": {
      "id": "TjAwNFVzZXI4NjE",
      "username": "your.username@example.com"
    }
  }
}
```

## Migration guidance

When migrating away from deprecated fields:

1. **Check the deprecation reason** -- it will tell you which new field or mutation to use.
2. **Update your queries** to use the replacement field.
3. **Test thoroughly** before removing the deprecated field from your code.
4. **Monitor Lumar's changelog** for announcements about upcoming deprecation removals.

Deprecated fields remain available for a reasonable transition period, but you should plan to migrate promptly to avoid disruption.