API changelog

Versioning policy

The CASRAI platform follows the conventional GraphQL practice of continuous evolutionrather than numbered API versions: the schema gains fields over time, never loses them without notice. Two axes are versioned separately.

• The dictionary content is versioned by release tag (for example v2026.1, v2026.2). Each release is an immutable snapshot of the served vocabulary; previous releases remain queryable via the release argument on the dictionaryTerms root field.
• The API surface — GraphQL schema and REST routes — evolves additively. New fields and routes ship continuously. Breaking changes are announced at least one quarter ahead on this page and on the news feed before they take effect.

What counts as breaking

• Renaming or removing a GraphQL field, type, enum value, or argument.
• Changing the nullability of an existing field from nullable to non-null in input position, or vice versa in output position.
• Removing or renaming a REST route, query parameter, or response property.
• Tightening a previously documented rate limit or auth requirement.
• Changing the meaning of an identifier — for example, repurposing a slug.

What does not count as breaking: adding new fields, types, arguments with sensible defaults, or routes; loosening rate limits; adding optional response properties.

Deprecation procedure

When a breaking change is required, the field, type, or route is marked deprecated and the following sequence applies. Subscribers to the (planned) event webhooks will receive an api.deprecation.scheduled event when each step fires.

1. Quarter T0: announce here; mark the field with GraphQL @deprecated(reason: ...) or a Deprecation HTTP header on REST responses.
2. Quarter T+1: introduce the replacement; emit a warning log line on every call to the deprecated path.
3. Quarter T+2: remove the deprecated field or route.

The minimum window from announcement to removal is therefore two quarters. Some changes have a longer window where downstream consumers (Crossref ingestion, ORCID propagation) require additional lead time.

Changelog

Entries are listed newest first. Dates are ISO-8601. Schema-level diffs link to the relevant release notes.

2026-05-12 — v2026.1

• Added (GraphQL): DictionaryTerm.relationships now exposes a targetUri field alongside targetSlug, enabling cross-vocabulary links to casrai.org/creditand other external term sets.
• Added (REST): the /dictionary/stats endpoint now returns release alongside last_modified. See the REST endpoints page.
• Deprecated (GraphQL): DictionaryTerm.legacyId — replaced by DictionaryTerm.canonicalUri. Removal scheduled for v2026.3 (2026-11).

2026-02-04 — v2025.4

• Added (GraphQL): DictionaryTerm.definedTermJsonLd returns a pre-rendered Schema.org DefinedTerm object, matching the shape documented on CRediT in JSON-LD.
• Removed (GraphQL): the legacy casraiId root query, deprecated in 2025-08. Use dictionaryTerm(id, idType: SLUG).
• Migration: legacy dictionary.casrai.org/Contributor_Roles/identifiers are no longer accepted as input. Use the canonical casrai.org/credit/roles/ URIs.

2025-11-18 — v2025.3

• Added (REST): /object-template and /picklistendpoints reached general availability with stable response shapes. See REST endpoints.
• Added (GraphQL): dictionaryDomains root field returns the full 20-domain index, supporting the domain index page.

2025-08-26 — v2025.2

• Added (GraphQL): dictionaryTerm(id, idType: SLUG) as the preferred lookup. casraiId deprecated; removal scheduled for v2025.4.
• Added (REST): Application Password authentication on write endpoints alongside cookie auth.
• Policy: public read rate limit raised from 30 to 60 requests/minute per IP after operational review.

2025-05-15 — v2025.1

• Initial public release of the GraphQL endpoint and the /wp-json/casrai/v1/ REST namespace.
• Scope: read access to dictionary terms, object templates, picklists, and the 14 CRediT roles, including the canonical casrai.org/credit URIs.

How to detect deprecations programmatically

For GraphQL, introspect the schema and look for the isDeprecated flag on each field; CI jobs can fail when they depend on a deprecated field that is scheduled for removal.

query DeprecatedFields {
  __type(name: "DictionaryTerm") {
    fields(includeDeprecated: true) {
      name
      isDeprecated
      deprecationReason
    }
  }
}

For REST, watch for the standard Deprecation and Sunset response headers as specified in RFC 8594and the Deprecation HTTP Header Field (RFC 9745).

curl -sI "https://casrai.org/wp-json/casrai/v1/dictionary-term?slug=research-integrity" \
  | grep -iE '^(deprecation|sunset|link):'

Related

• GraphQL endpoint — the schema this changelog tracks.
• REST endpoints — the REST routes this changelog tracks.
• Event webhooks — the planned source of api.deprecation.scheduled events.
• News — long-form change announcements with migration guidance.