Schema-introspectie

GraphQL heeft ingebouwde introspectie: je kunt het schema zelf bevragen om te ontdekken welke queries, types en velden beschikbaar zijn. Dit is handig bij het bouwen van scripts of het verkennen van beschikbare data.

Alle introspectiequery's gebruiken hetzelfde endpoint en dezelfde authenticatie als gewone queries.

Alle beschikbare queries weergeven

{
  __schema {
    queryType {
      fields {
        name
        description
      }
    }
  }
}

Dit geeft de volledige lijst van root query-velden terug — bijvoorbeeld controls_paged, activities_paged, risks_paged enzovoort.

Alle beschikbare mutations weergeven

Mutations werken op dezelfde manier — bevraag mutationType in plaats van queryType:

{
  __schema {
    mutationType {
      fields {
        name
        description
      }
    }
  }
}

Dit geeft elke mutation terug die je kunt aanroepen — bijvoorbeeld addExecution, addEvidenceToExecution enzovoort.

Info

Een read-only machine-to-machine-credential kan mutations wel introspecteren (de namen opvragen), maar niet uitvoeren. Authenticeer via de Device Authorization Grant zodat je token schrijfrechten heeft om een mutation uit te voeren.

De argumenten van een mutation inspecteren

Voeg args toe om te zien welke invoer elke mutation verwacht:

{
  __schema {
    mutationType {
      fields {
        name
        args {
          name
          description
          type {
            name
            kind
            ofType {
              name
              kind
            }
          }
        }
      }
    }
  }
}

Als een argument een input-object is (bijvoorbeeld ExecutionInput), inspecteer dan de velden met __type en inputFields:

{
  __type(name: "ExecutionInput") {
    inputFields {
      name
      description
      type {
        name
        kind
        ofType {
          name
        }
      }
    }
  }
}

Zie Bewijs toevoegen voor een uitgewerkt voorbeeld waarin meerdere mutations aan elkaar worden geknoopt.

Een specifiek type inspecteren

Gebruik __type om de velden van een type op te vragen:

{
  __type(name: "Activity") {
    fields {
      name
      description
      type {
        name
        kind
        ofType {
          name
          kind
        }
      }
    }
  }
}

Vervang "Activity" door een willekeurige typenaam — bijvoorbeeld "Control", "Risk", "Issue" of "Assessment".

Enum-waarden weergeven

Gebruik dit om de geldige waarden van een enum-type op te vragen:

{
  __type(name: "ActivityDueStatus") {
    enumValues {
      name
    }
  }
}

Veelgebruikte enums om te inspecteren: ActivityDueStatus, Effectiveness, ControlCategory, Priority, IssueType.

Volledig Python-voorbeeld

Dit script authenticeert en print een samenvatting van het schema: alle query-velden en de velden van een opgegeven type.

import requests
import json
import time

TENANT = "{jouw-tenant}"
BASE_URL = f"https://auth.tidalcontrol.com/realms/{TENANT}/protocol/openid-connect"
CLIENT_ID = "portal"
GRAPHQL_URL = "https://portal.tidalcontrol.com/graphql"


def get_token():
    r = requests.post(
        f"{BASE_URL}/auth/device",
        data={"client_id": CLIENT_ID, "scope": "openid"},
    )
    r.raise_for_status()
    device = r.json()

    print(f"\nOpen deze URL in je browser om in te loggen:")
    print(f"  {device['verification_uri_complete']}\n")

    interval = device.get("interval", 5)
    deadline = time.time() + device["expires_in"]

    while time.time() < deadline:
        time.sleep(interval)
        r = requests.post(
            f"{BASE_URL}/token",
            data={
                "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
                "client_id": CLIENT_ID,
                "device_code": device["device_code"],
            },
        )
        if r.status_code == 200:
            print("Authenticatie geslaagd.")
            return r.json()
        body = r.json()
        if body.get("error") == "authorization_pending":
            continue
        if body.get("error") == "slow_down":
            interval += 5
            continue
        r.raise_for_status()

    raise RuntimeError("Authenticatie verlopen.")


def graphql(query, access_token):
    r = requests.post(
        GRAPHQL_URL,
        json={"query": query, "variables": {}},
        headers={"Authorization": f"Bearer {access_token}"},
    )
    r.raise_for_status()
    result = r.json()
    if "errors" in result:
        raise RuntimeError(result["errors"])
    return result["data"]


def list_queries(access_token):
    data = graphql(
        "{ __schema { queryType { fields { name description } } } }",
        access_token,
    )
    fields = data["__schema"]["queryType"]["fields"]
    print(f"\n{len(fields)} query-velden beschikbaar:\n")
    for f in sorted(fields, key=lambda x: x["name"]):
        desc = f.get("description") or ""
        print(f"  {f['name']:<40} {desc}")


def describe_type(type_name, access_token):
    data = graphql(
        f'{{ __type(name: "{type_name}") {{ fields {{ name description '
        f'type {{ name kind ofType {{ name }} }} }} }} }}',
        access_token,
    )
    t = data.get("__type")
    if not t:
        print(f"Type '{type_name}' niet gevonden.")
        return
    print(f"\nVelden van {type_name}:\n")
    for f in t["fields"]:
        type_info = f["type"]
        type_name_str = type_info.get("name") or (type_info.get("ofType") or {}).get("name", "")
        print(f"  {f['name']:<30} {type_name_str}")


if __name__ == "__main__":
    token = get_token()
    access_token = token["access_token"]

    list_queries(access_token)
    describe_type("Activity", access_token)
    describe_type("Control", access_token)