GraphQL Query-Cost Control for an Offshore API Team

Derive cost from schema work

Build cost from schema semantics rather than string length. Assign documented weights to expensive fields, bound list multipliers by enforced pagination, account for aliases and fragments, and decide how interface or union selections contribute. Compare estimated cost with resolver calls, database queries, downstream requests, rows scanned, response bytes, and elapsed time for a controlled corpus. Include shallow-wide, deep-narrow, repeated aliases, nested lists, introspection according to policy, persisted operations, privileged fields, and a query that approaches but does not cross the limit. A static score cannot replace runtime timeouts, pagination, batching, caching, and authorization. Return a stable safe error that does not reveal internal weights unnecessarily. API owners set budgets and exceptions; schema owners maintain weights; the developer implements deterministic analysis and shows where observation contradicts the model.

Start with the fields that perform database scans, downstream calls, search, file work, or list expansion. Assign a documented weight only after describing that work. A character count or depth limit cannot see a shallow query that opens several wide lists. Conversely, a deeply nested selection over one bounded object may be cheap. Keep the weight table beside the schema revision it describes.

Make list multiplication explicit

Enforce pagination arguments in resolvers and in the scorer. Record the default, maximum, and behavior when the argument is missing or invalid. Multiply nested lists according to the bounded values the server will actually honor. If the scorer assumes ten items but a resolver accepts an unbounded value, the estimate is not conservative; it is disconnected from execution.

Interfaces and unions require a declared rule for possible selections. Fragments should be expanded before scoring, aliases should not make repeated expensive work free, and circular-fragment handling must terminate cheaply. Use normalized synthetic operations to prove those parser paths without retaining production variables.

Buyer decision record

Scroll sideways to read every column on a small screen.

Build a corpus that challenges the model

Include a shallow-wide query, a deep-narrow query, repeated aliases, nested lists, fragments shared across branches, an operation with several named queries, a persisted operation, introspection according to policy, a privileged field, and operations just below and above the threshold. Save the selected operation name and expected score for each fixture. A test suite made only of obvious attack queries will miss false rejections in normal product work.

Run the corpus under two roles when authorization changes visible fields or list sizes. The score must not accidentally grant access, and authorization must not be counted as a resource control. Decide whether a privileged operation receives a separate reviewed budget or must fit the common limit.

Compare estimates with several resource signals

For each fixture, collect resolver invocations, database calls, rows scanned, downstream requests, response bytes, elapsed time, and any timeout. DataLoader may reduce call count without reducing rows or payload, so one metric cannot validate the model. Plot or tabulate estimate beside observation and keep the outliers. Those outliers are where weights, resolver design, or the control boundary needs more work.

Repeat the corpus with a warm and cold cache if caching materially changes execution. The static score should describe permitted work, not depend on a lucky cache hit. Runtime deadlines, pagination, batching, cache policy, and downstream circuit breakers remain necessary even after the score correlates well.

Design rejection as part of the API contract

Store the normalized operation and selected operation name for synthetic cases, but never retain production variables unnecessarily. Expand fragments before scoring and prevent circular-fragment handling from consuming resources itself. Enforce actual page-size arguments server-side; a scoring assumption about a default is unsafe if resolvers accept an unbounded value. DataLoader can reduce calls without reducing rows or downstream payloads, so compare several resource signals. Cost exceptions need a caller, operation hash, ceiling, purpose, and expiry. Schema changes that add a list field or alter resolver behavior should trigger corpus replay. The handoff includes false-positive and false-negative examples so maintainers understand where the model remains conservative or incomplete.

Return a stable error that clients can distinguish from authentication, validation, and server failure. Avoid publishing enough internal weight detail to make the schema easier to probe unless the API intentionally exposes a cost contract. Test that rejection happens before expensive resolvers start and that telemetry records a safe operation identifier, caller class, estimate, limit, and outcome.

Give exceptions an end date

An exception needs a caller, normalized operation hash, business purpose, approved ceiling, owner, and expiry. Do not exempt an entire client or disable analysis for persisted queries. Replay exceptions whenever the schema or resolver behavior changes. At expiry, the operation should return to the standard budget unless an owner reviews new evidence.

Track false positives, false negatives, rejected operations, runtime overruns below the threshold, and overrides still in use. An operation whose low score repeatedly produces high work is a model defect. A high-scoring operation that executes cheaply may point to a weight that is too coarse, but lowering it requires corpus evidence rather than pressure from one client.

Retest when the schema changes

A new list field, altered pagination maximum, resolver rewrite, or downstream fan-out can invalidate yesterday’s weights without changing an existing operation text. Make corpus replay part of schema review and compare both scores and observed work. Store the schema and scorer revisions with the result so a later discrepancy can be reproduced.

Release with a maintained scoring model

The control passes when deterministic estimates reject seeded expensive operations, allow representative safe work, and correlate sufficiently with observed fan-out to support the declared budget. Unbounded list multipliers, bypass through fragments or aliases, unexplained false rejects, and undocumented overrides block rollout.

The API owner receives the schema revision, weight table, pagination enforcement, parser rules, complete corpus, expected and actual scores, resource observations, rejection contract, runtime safeguards, exception register, telemetry, and re-test triggers. Schema owners maintain weights when fields change. The developer implements deterministic scoring and fixtures, but cannot grant an undocumented override or treat the static model as a substitute for operational limits.

Questions about assessing Philippine developers