GraphQL

The GraphQL endpoint exists for callers that need related data in one round trip and want to choose which fields come back - reporting tools, analytics pipelines, dashboards and portals assembling a view from several parts of the system at once.

When to use it instead of REST

The usual case for GraphQL is a reporting client that would otherwise make one call for a document, another for its lines, another for the accounts each line touches, and another for the approver on each - four round trips becoming one request.

Access and authentication

The same model as REST: credentials are issued per deployment by its operator, each integration has its own identity and its own permissions, tokens are time-limited and TLS is required. A GraphQL credential is not a wider credential - it reaches exactly the same data the same integration would reach over REST.

Authorisation is per field, not per call

This is the part worth understanding before designing against it. Because the caller chooses the fields, permissions are applied per field and per record, not once at the start of the request.

An integration that may not see a salary figure cannot obtain it by reaching that field through a relationship. Where a requested field is not permitted, the response says so explicitly rather than silently returning null - so a permissions problem looks like a permissions problem, not like missing data.

Limits every deployment enforces

A GraphQL endpoint without limits is a denial-of-service endpoint with a schema attached. Every deployment applies:

• Query depth limits, so a recursive relationship cannot be used to walk the whole database.
• A complexity budget, scored before execution. Depth alone does not stop a very wide query.
• Page-size caps on every collection, enforced by the server.
• Timeouts on every resolver path.
• Rate limits, as with REST.
• Introspection disabled in production unless an integration specifically requires it.

A query that exceeds a limit is rejected with a clear reason. That is deliberate: a rejection you can read is better than a timeout you have to guess about.

Writing your queries well

Ask for what you need. The field selection is the point - requesting everything removes the advantage over REST and pushes you towards the complexity budget.

Page deliberately. Request a page size you will actually use; the server cap is a ceiling, not a target.

Batch at the top, not the bottom. Fetching a list and then a detail query per item is the pattern GraphQL exists to avoid.

Expect additive change. New fields and types appear over time; your client should ignore what it does not recognise.

What it is not for

Bulk extraction. Pulling an entire dataset through paged queries is slow for you and expensive for the deployment. Where a full periodic extract is genuinely needed, ask the operator for a scheduled export - the data is written once, to a location you collect from, without holding a connection open for the duration.

Getting started

The available types and operations depend on which modules a deployment runs, so the operator provides the schema alongside credentials. If you are evaluating d1kit for a new build, get in touch.