API 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:

Query

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

Response

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

cURL

curl -X POST -H "Content-Type: application/json" -H "apollographql-client-name: docs-example-client" -H "apollographql-client-version: 1.0.0" -H "x-auth-token: YOUR_API_SESSION_TOKEN" --data '{"query":"query GetReportTemplateWithDatasource { getReportTemplates(first: 1) { nodes { code name datasourceCodeEnum } } }"}' https://api.lumar.io/graphql

Try in explorer

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 indicates deprecated fields.

Checking the API

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

Query

query GetApiVersion {
  me {
    id
    username
  }
}

Response

{
  "data": {
    "me": {
      "id": "TjAwNFVzZXI4NjE",
      "username": "your.username@example.com"
    }
  }
}

cURL

curl -X POST -H "Content-Type: application/json" -H "apollographql-client-name: docs-example-client" -H "apollographql-client-version: 1.0.0" -H "x-auth-token: YOUR_API_SESSION_TOKEN" --data '{"query":"query GetApiVersion { me { id username } }"}' https://api.lumar.io/graphql

Try in explorer

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.