Technology · 10 min

Write an Architecture Decision Record for migrating from REST to GraphQL

Archetype: Planner Tier 2

Context

A mid-size SaaS platform team is evaluating migrating their public API from REST to GraphQL. The lead architect must produce an Architecture Decision Record that documents the rationale, trade-offs, and implementation constraints for the engineering leadership to approve or reject the proposal.

Before (Unstructured)

"Write an Architecture Decision Record for migrating from REST to GraphQL."

What is missing

× No organizational context — team size, current architecture, or scale mentioned
× No decision framework — how should alternatives be evaluated?
× No constraints — timeline, backward compatibility, or performance requirements
× No audience defined — who reviews and approves this ADR?
× No success criteria — what makes this ADR decision-ready?

After (MOTIVE-Structured)

[M] Motivation

As the lead architect for a SaaS platform serving 2,000+ API consumers, I need an Architecture Decision Record because the team is evaluating REST-to-GraphQL migration, and engineering leadership requires a documented rationale to approve or reject the proposal.

[O] Object

Deliver an ADR following the Michael Nygard template with sections: Context, Decision, Status, Consequences. Success criteria: (1) All three alternatives evaluated with pros/cons, (2) Migration risks quantified, (3) Backward compatibility strategy defined.

[T] Tool

Use the Michael Nygard ADR template. Apply the C4 model for architecture context. Reference the GraphQL Foundation best practices for API design patterns.

[I] Instruction

1. Document current REST API architecture (endpoints, traffic, pain points). 2. Define evaluation criteria (performance, developer experience, maintenance cost, backward compatibility). 3. Evaluate three alternatives: (a) Full GraphQL migration, (b) GraphQL gateway over REST, (c) Hybrid approach. 4. Recommend one option with phased rollout plan. If performance benchmarks are unavailable, flag as requiring proof-of-concept.

[V] Variables

Current state: 47 REST endpoints, 2,000+ consumers, 50M requests/month. Team: 4 backend engineers. Audience: VP Engineering, Staff Engineers. Format: ADR markdown document. Timeline constraint: Decision needed by end of Q2. Exclude: Frontend framework changes, authentication redesign.

Output Comparison

Before Output

GraphQL is better than REST because it allows clients to request only the data they need. You should migrate to GraphQL to improve your API. It will reduce over-fetching and under-fetching problems. Many companies like Facebook and GitHub use GraphQL.

Show full output

GraphQL is a great technology that is becoming increasingly popular in the industry. It allows clients to request exactly the data they need, which is much better than REST where you often get too much or too little data. Many leading companies like Facebook, GitHub, and Shopify have already adopted GraphQL with great success. You should definitely consider migrating to GraphQL for your API. The main benefits include reduced over-fetching, a strongly typed schema, and a better developer experience. GraphQL also provides built-in introspection, which makes it easier for developers to explore and understand your API. The migration process is straightforward. You can start by creating a GraphQL schema that maps to your existing data models, then implement resolvers for each field. There are many great libraries and tools available, such as Apollo Server and GraphQL Yoga, that make it easy to get started. GraphQL also supports real-time features through subscriptions, which can be valuable for your analytics dashboard use case. Overall, moving to GraphQL will modernize your API and make your platform more developer-friendly. The community is large and growing, so you will find plenty of resources and support.

After Output

Alternative B: GraphQL Gateway over REST (Recommended). Evaluation: Performance: +15% reduction in payload size (estimated from current 47-endpoint over-fetching analysis). Developer Experience: New consumers use GraphQL; existing 2,000+ consumers retain REST unchanged. Migration Risk: LOW — no breaking changes to existing contracts. Cost: 3 engineer-months for gateway layer. Backward Compatibility: Full — REST endpoints remain operational indefinitely.

Show full output

**ADR-0042: API Query Layer Migration Strategy** Status: Proposed. Date: 2026-02-15. Decision Makers: VP Engineering, Staff Engineers. Context: The SaaS platform serves 2,000+ API consumers through 47 REST endpoints handling 50M requests/month. Current pain points: (1) Average response payload is 340% larger than client needs due to fixed endpoint schemas, (2) Mobile clients require 3-4 sequential REST calls for single-view rendering, (3) 12 engineer-hours/week spent maintaining endpoint variants for different consumer needs. **Alternatives Evaluated** Alternative A — Full GraphQL Migration: Replace all 47 REST endpoints with GraphQL. Performance: +40% payload reduction. Risk: CRITICAL — breaks all 2,000+ existing integrations. Cost: 8 engineer-months. Backward compatibility: None without versioned gateway. Verdict: Rejected due to unacceptable consumer disruption. Alternative B — GraphQL Gateway over REST (Recommended): Deploy a GraphQL gateway layer that delegates to existing REST services. Performance: +15% payload reduction (estimated from current over-fetching analysis). Developer Experience: New consumers use GraphQL; existing 2,000+ retain REST unchanged. Migration Risk: LOW — no breaking changes to existing contracts. Cost: 3 engineer-months for gateway layer. Backward Compatibility: Full — REST endpoints remain operational indefinitely. Alternative C — Hybrid with Selective Endpoint Replacement: Migrate top-10 high-traffic endpoints to GraphQL, maintain remaining 37 as REST. Performance: +25% payload reduction on migrated endpoints. Risk: MEDIUM — 10 endpoint migrations affect ~800 consumers. Cost: 5 engineer-months. Backward Compatibility: Partial — requires consumer migration for affected endpoints. **Migration Risk Matrix & Phased Rollout** Phase 1 (Weeks 1-4): Deploy GraphQL gateway for internal consumers only. Success gate: <50ms added latency at p99. Phase 2 (Weeks 5-8): Open GraphQL access to beta partner program (20 consumers). Success gate: Zero breaking changes detected. Phase 3 (Weeks 9-12): General availability with developer documentation and migration guide. Rollback plan: Gateway can be disabled at load balancer level with zero impact on REST endpoints. Monitoring: Track query complexity scores, resolver performance, and error rates per consumer.

Evaluation Scores

Average Before

1.5/5

Average After

4.3/5

Improvement

+183%

Before MOTIVE (1-5)

After MOTIVE (1-5)

Key Improvement

The Variables component produced the largest impact by specifying the 2,000+ consumer base, 50M monthly requests, and backward compatibility requirement — forcing the analysis to address real constraints rather than abstract technology preferences.

Develop a competency framework for data literacy across a 500-person organization

→