Third-Party GraphQL Schema Monitor

Monitor authorized third-party GraphQL introspection endpoints for schema drift. The Actor keeps an explicit cross-run baseline and emits GraphQL-aware change records for breaking, dangerous, additive, and other structural changes.

This is useful when your application depends on a vendor or partner GraphQL API but you do not control its deployment pipeline or schema registry.

What it does

For each endpoint, the Actor:

1. sends one fixed standard GraphQL introspection query;
2. validates and bounds the JSON response;
3. rebuilds a GraphQL schema with graphql-core;
4. normalizes the schema to deterministic SDL;
5. compares it with the previous successful schema in a named key-value store;
6. classifies changes and writes one dataset row;
7. charges graphql_schema_check only after the successful schema is stored.

Typical statuses are:

• initial_snapshot — first valid schema stored;
• unchanged — normalized schema matches the previous successful check;
• changed — schema changed, with bounded details;
• fetch_error — network, redirect, TLS, HTTP, or destination validation failed;
• schema_error — response was not usable bounded introspection JSON/schema;
• state_error — a stored baseline could not be rebuilt safely.

Failures are not charged and do not replace a successful baseline.

Input

Field	Type	Default	Description
monitorId	string	qa-default	Stable watchlist ID. Changing it creates a separate baseline namespace.
endpointUrls	string[]	public Countries GraphQL example	1–50 authorized public HTTPS GraphQL endpoints. Duplicate URLs are checked once.
authorizationHeader	secret string	empty	Optional complete Authorization value shared by every endpoint in the run, such as Bearer …. Never logged or persisted.
timeoutSeconds	integer	30	Total per-endpoint check timeout, 5–60 seconds.
maxChanges	integer	200	Maximum detailed changes in one result, 1–500. Summary counts remain present.
maxConcurrency	integer	5	Concurrent endpoint checks, 1–5.

Example:

{
  "monitorId": "partner-graphql-production",
  "endpointUrls": [
    "https://api.example.com/graphql"
  ],
  "authorizationHeader": "Bearer <authorized-read-only-token>",
  "timeoutSeconds": 30,
  "maxChanges": 200,
  "maxConcurrency": 3
}

Only use endpoints and credentials you are authorized to query. The Actor does not discover endpoints, bypass disabled introspection, or send arbitrary GraphQL operations.

Output

Each dataset row includes:

• endpoint, final URL, HTTP status, content type, and check time;
• stable current/previous SHA-256 schema hashes;
• type, field, argument/input-field, enum-value, and directive counts;
• status and concise summary;
• breaking, dangerous, additive, and informational counts;
• bounded change details (severity, type, location, description);
• named-state mode and charge-event fields;
• a bounded error on non-billable failures.

Example changed row:

{
  "endpoint_url": "https://api.example.com/graphql",
  "status": "changed",
  "type_count": 42,
  "field_count": 318,
  "breaking_count": 1,
  "dangerous_count": 1,
  "additive_count": 2,
  "informational_count": 0,
  "change_count": 4,
  "changes": [
    {
      "severity": "breaking",
      "type": "FIELD_REMOVED",
      "location": "schema",
      "description": "Product.legacyName was removed."
    }
  ],
  "state_store_mode": "named_key_value_store",
  "charged_event": "graphql_schema_check"
}

Change labels follow GraphQL type-system rules, but they are review aids—not proof of actual client impact. A schema-level breaking change may not affect operations your application uses. Runtime behavior can also change without schema drift.

Persistent state

State is stored in the explicit named key-value store:

third-party-graphql-schema-monitor-state-v1

Keys are SHA-256 digests of monitorId plus endpoint URL. Stored snapshots contain normalized schema SDL, hashes, counts, and source metadata. They never contain the optional Authorization value. Failed checks do not overwrite the last successful schema.

Use the same monitorId and endpoint URL on scheduled runs to reuse history. Use a new monitorId for an independent baseline.

Security and limits

Production checks enforce:

• public HTTPS on port 443 only;
• no URL credentials, fragments, whitespace, or control characters;
• private, loopback, link-local, multicast, reserved, and other non-global destinations blocked;
• every destination resolved and the connection pinned to a validated IP;
• every redirect re-resolved;
• cross-origin redirects rejected so Authorization cannot leave the configured origin;
• fixed introspection POST only—no user-controlled GraphQL query;
• two bounded attempts and at most five redirects within one total timeout;
• identity encoding only, 2 MB response cap, bounded UTF-8/JSON parsing, duplicate-key rejection;
• depth/node/schema type/field/input/enum limits;
• at most 50 endpoints and five concurrent checks;
• error truncation and secret redaction;
• no raw response or credential persistence.

For least privilege, use a read-only credential limited to schema introspection. Avoid sharing one secret across unrelated providers because authorizationHeader applies to every endpoint in the run; use separate runs when credentials differ.

Pricing

The intended Store model is pay per event:

• event: graphql_schema_check;
• one event only after a schema is fetched, validated, compared, and stored;
• input, destination, HTTP, introspection, parse, schema, and state failures are not charged by this custom event.

The Actor respects Apify's per-run PPE cost limit before starting bounded endpoint work.

Limitations

• Many production GraphQL services disable introspection to reduce attack surface. The Actor cannot monitor those endpoints unless the provider exposes introspection to an authorized credential.
• The fixed compatibility-oriented introspection query omits newer optional introspection fields so it works with more servers. Changes visible only through omitted optional metadata may not be detected.
• This is not a schema registry for an API owner, a GraphQL traffic analyzer, operation registry, vulnerability scanner, or availability SLA.
• The Actor does not validate your actual queries against the new schema or calculate client-specific blast radius.
• Endpoint availability, schema accuracy, and usage rights remain the provider's and user's responsibility.

Local development

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
python smoke_test.py
npx --yes apify-cli validate-schema
PATH="$PWD/.venv/bin:$PATH" npx --yes apify-cli run --purge

The deterministic smoke test proves initial_snapshot → unchanged → schema_error → unchanged → changed, baseline preservation after failure, GraphQL breaking/dangerous/additive classifications, duplicate/deep JSON rejection, private-target blocking, Authorization redaction, and cross-origin redirect blocking.

Independence and lawful use

This is an independent utility and is not affiliated with or endorsed by the GraphQL Foundation, Apollo, The Guild, GitHub, GitLab, Twenty, dotCMS, the public default example, or any monitored API provider. GraphQL and third-party names belong to their respective owners.

You are responsible for authorization, provider terms, polling frequency, credential scope, and decisions based on the results. The default endpoint is a public community example for QA; replace it with an endpoint you are authorized to monitor.