GraphQL tradeoffs should be decided before a team generates its first schema file. The technology can make a product easier to compose, but the first build also creates a public vocabulary, a resolver execution path, a security surface, and a release contract. A short decision record forces the team to answer the questions a demo can postpone: which client task needs field selection, which system owns each fact, what query cost is acceptable, who may see which combination, and how a field will be changed without surprising a client.
Write the client problem in observable terms
Start with one real screen or workflow. Describe the user, the decision they make, the data currently needed, the number of systems involved, and the coordination cost of changing the representation. “We want a flexible API” is too broad. “The account overview needs current plan, usage, invoices, and open support cases in a different shape on web and mobile” is specific enough to test. The GraphQL Queries guidance explains typed selection sets and traversal; it does not tell the team whether that flexibility is the best answer to this journey.
| Decision record field | What to write down | Why it matters |
|---|---|---|
| Client task | The screen, actor, and decision supported. | Prevents an architecture demo from becoming the goal. |
| Authority | Source of truth for each business fact. | Avoids hiding ownership problems in resolvers. |
| Shape | Fields, nullability, lists, and errors the client needs. | Makes the first contract reviewable. |
| Cost | Depth, page size, downstream calls, and latency budget. | Keeps flexibility from becoming unbounded work. |
| Change | Deprecation, compatibility, and removal evidence. | Makes the schema an evolvable product boundary. |
Model business facts before interface convenience
Sketch the domain concepts and relationships the client actually uses. Resist a one-to-one database mapping because table names, joins, and migration details rarely make durable client language. Decide whether a field represents a current state, a historical fact, an estimate, or a permission-filtered view. If two services disagree on a customer’s status, do not hide the conflict behind a nullable field. Record the authority, freshness, and error semantics in the schema design.
A field should have an owner who can answer whether it is correct, when it changes, and what happens when its source is unavailable. The GraphQL schema design guidance supports modeling the domain and evolving types over time. Use descriptions and examples that explain business meaning, not only implementation. If a type is an internal aggregation that no team wants to own, it is probably too broad for the first slice.
Set operation, transport, and failure boundaries
Separate reads from writes in the decision record. A read query can often tolerate partial data or a delayed refresh if the interface makes that state clear. A mutation needs validation, idempotency, concurrency behavior, authorization, and a user-visible result. Do not add mutations because a GraphQL endpoint should look complete. First prove that the read composition reduces the specific coordination pain you named.
Define how the GraphQL service will be exposed over HTTP. The official Serving over HTTP guidance describes a common single endpoint, authentication before GraphQL execution, POST for queries and mutations, optional GET for queries, and structured data and errors in the response. Treat those as transport choices to verify against your clients and intermediaries. A transport convention is not a substitute for an application contract, but an unexamined convention can still create cache, proxy, or compatibility surprises.
| Boundary | First-build decision | Failure question |
|---|---|---|
| HTTP | Endpoint, methods, media types, and request limits. | What does a malformed or oversized request receive? |
| Schema | Types, nullability, lists, and deprecation policy. | How does a client distinguish absent from denied? |
| Resolver | Owner, downstream calls, and timeout budget. | What happens when one source is unavailable? |
| Mutation | Idempotency, state transition, and result meaning. | Can a retry create a second effect? |
| Authorization | Role and action checks at the business boundary. | Can another resolver bypass the same rule? |
Put query limits and authorization into the design
A GraphQL query is executable work, not just a document. Before code, set a maximum useful page size, depth or complexity policy, timeout, rate limit, and response size. Decide whether the first clients may send arbitrary operations or only trusted documents. The GraphQL Security guidance highlights the need to protect services from malicious or expensive operations. Choose controls that the team can explain and monitor; an opaque complexity number is not enough if no one knows which operation exceeded it.
Place authorization where the business decision is made. Check not only whether a user may read a type, but whether they may request a field combination or perform the action represented by a mutation. Keep safe public errors separate from protected diagnostics. Test a role that can see an account but not its payment details, and a role that can read a summary but not a raw identifier. Write those negative examples before the first build so they shape the schema rather than arrive as a patch.
Make lists and client traversal predictable
Lists are where a flexible query becomes an unbounded data pull. Choose a connection or page model, define ordering, cursor stability, maximum page size, and behavior when records change between requests. The official Pagination guidance describes the value of consistent traversal and page information. For the first build, include one representative empty page, one last page, and one case where the underlying data changes while a client is traversing.
Do not make pagination a frontend-only detail. It affects resolver cost, authorization scope, cache keys, and the user’s expectation of completeness. If a client needs a count, specify whether it is exact, estimated, or expensive. If a report needs bulk export, give it a deliberate job or file boundary instead of allowing a deeply nested query to become an accidental export API. The REST API contracts guide is a useful comparison when a resource-oriented list is clearer.
Plan compatibility before publishing the first field
Schema evolution is easier when the first field already carries a description, owner, example, usage expectation, and replacement plan. Additive changes are not automatically safe if clients use strict generated models or if a new field changes resolver load. Mark replacements deprecated with a reason, observe real usage, and set a review date for removal. Avoid versioning every schema by default; first decide which compatibility contract clients actually need.
Keep the GraphQL layer alongside existing interfaces while evidence accumulates. A client can migrate one operation at a time, and the team can compare response correctness, latency, downstream call count, and support demand. Link the decision to API versioning before the first build when a client needs a compatibility window, to test strategy for custom software for contract, authorization, and failure tests, and to the authentication decision guide when the graph crosses an identity boundary.
Build a first slice that can teach you something
Choose a read journey with enough composition to reveal whether the graph helps, but not so much scope that every service must change. Record the current integration effort as a baseline. Implement the smallest schema that supports the journey, instrument operation names, resolver latency, downstream calls, query rejection, and partial errors, then expose it to a limited client cohort. Keep a direct authority path for the values that influence money, entitlements, or irreversible actions.
Use the decision record after the launch
After the first slice, revisit the original hypothesis. Did client changes become faster? Did the schema clarify or obscure ownership? Which queries cost more than expected? Did users receive partial results they could interpret? Did a new field create a dependency that now needs a stronger contract? Keep the answers beside the schema so the next team does not treat an experiment as a permanent platform mandate.
A good review can conclude that GraphQL is useful for one product area and unnecessary for another. That is a successful architecture decision. The aim is not to make every capability look the same; it is to make the boundary that fits the user outcome, security model, and operating capacity understandable.
Key takeaways
- Start with a real client decision and a measurable coordination problem.
- Model owned business facts instead of exposing storage structure by convenience.
- Define transport, operation, pagination, authorization, cost, and failure behavior before coding.
- Use a narrow read slice to learn whether flexibility pays for its operating responsibility.
- Keep compatibility and retirement evidence beside the schema from the first field onward.
Frequently asked questions
What should be decided before building a GraphQL API?
Write the client journey, authoritative facts, schema and operation boundaries, access rules, query limits, compatibility promise, owners, and first-slice evidence. That record lets the team debate the product boundary before implementation details make the choice feel inevitable.
How should a team prevent expensive GraphQL queries?
Set page, depth, complexity, timeout, and response-size limits; batch related resolver work; use trusted documents where appropriate; and measure cost by named operation. Make rejected queries visible so the team can adjust a legitimate client or contain an abusive one.
Should the first build include federation or subscriptions?
Only when the first user outcome needs them and the team can operate the added contracts. A focused query and read model usually reveals more about domain ownership and cost than a broad platform build.
Conclusion: decide the GraphQL boundary before the code
GraphQL tradeoffs are easier to govern when the first build begins with a decision record. Tie the schema to a client task, make authority and access explicit, bound execution, and measure a reversible slice. The result may be GraphQL, a simpler API, or a combination; the important outcome is a boundary the team can explain and evolve.