Language SDKs

Status

Three first-party SDKs are planned: @casrai/sdk for JavaScript and TypeScript, casrai on PyPI for Python, and casrai on CRAN for R. None are published yet. The work is scheduled for Phase 5 of the platform roadmap, after the MCP server and the webhook surface.

Until the SDKs ship, the recommended access pattern is the GraphQL endpoint driven by a standard HTTP or GraphQL client. The endpoint is small, stable, and well documented; an SDK adds typed query helpers and ergonomic defaults, but no capability you cannot reach today with fetch or requests.

What the SDKs will provide

The SDKs are deliberately scoped to be thin. Each one will offer:

A typed client with the GraphQL schema bundled, so that misnamed fields fail at compile or import time.
Pre-built helpers for the most common reads — getTerm(slug), listTerms({ domain }), getPicklist(slug), getObjectTemplate(slug), listCreditRoles().
An optional caching layer keyed on dictionary release, so that calls within a release version do not re-hit the network.
Helpers for emitting JATS XML and JSON-LD from in-memory contributor structures.
Convention-over-configuration defaults: production endpoint, sensible timeouts, exponential back-off on 429.

Today's recommended pattern

In the absence of an SDK, the canonical pattern is a POST to the GraphQL endpoint with a JSON body containing query and optionally variables. The example below fetches a term by slug from JavaScript.

Plain fetch against the GraphQL endpoint

javascript

const ENDPOINT = "https://casrai.org/graphql";

async function getTerm(slug) {
  const query = `
    query GetTerm($slug: ID!) {
      dictionaryTerm(id: $slug, idType: SLUG) {
        slug
        title
        status
        version
        canonicalUri
        definitionOperational
      }
    }
  `;

  const res = await fetch(ENDPOINT, {
    method:  "POST",
    headers: { "Content-Type": "application/json", "Accept": "application/json" },
    body:    JSON.stringify({ query, variables: { slug } }),
  });

  if (!res.ok) throw new Error(`CASRAI ${res.status}`);
  const { data, errors } = await res.json();
  if (errors) throw new Error(errors.map(e => e.message).join("; "));
  return data.dictionaryTerm;
}

console.log(await getTerm("research-integrity"));

The same shape, translated to Python with requests:

Plain requests against the GraphQL endpoint

python

import requests

ENDPOINT = "https://casrai.org/graphql"

QUERY = """
query GetTerm($slug: ID!) {
  dictionaryTerm(id: $slug, idType: SLUG) {
    slug title status version canonicalUri definitionOperational
  }
}
"""

def get_term(slug: str) -> dict:
    r = requests.post(
        ENDPOINT,
        json={"query": QUERY, "variables": {"slug": slug}},
        headers={"Accept": "application/json"},
        timeout=10,
    )
    r.raise_for_status()
    payload = r.json()
    if payload.get("errors"):
        raise RuntimeError(payload["errors"])
    return payload["data"]["dictionaryTerm"]

print(get_term("research-integrity"))

For richer worked examples in JavaScript, Python, and PHP — including JSON-LD rendering and CRediT statement construction — see code examples.

Influence the SDK design

The SDK scope is still open to feedback. If your project would consume an SDK from a language not in the three above (Go, Rust, Java, Ruby), or if you need a particular helper not in the list above, raise it through the working-groups contact form at /contact/working-groups before Phase 5 starts.