Choosing between REST and GraphQL for your API

Every team building a modern web service eventually hits the same fork in the road. Should the public interface stick with tried-and-true REST endpoints, or should the schema-first world of GraphQL take the wheel? The honest answer rarely comes from blog posts or conference talks alone. It comes from understanding the trade-offs in the context of your product, your team, and the users on the other end of the wire.

Down here in Australia, that decision often lands on desks in Surry Hills offices, Melbourne co-working spaces, and increasingly from engineers dialling in from Perth or a regional hub. Timezone overlaps with Asia make overnight builds a habit, while keeping latency low for users on the east coast means the wrong architectural choice can quietly bleed performance from a product for years.

Understanding the core philosophies behind each approach

REST treats data as a collection of resources, each identified by a URL and acted on using HTTP verbs. Clients fetch a user, then fetch their orders, then fetch line items, and developers learn to compose these calls into the screens their users see. The model is intuitive, the documentation mature, and the tools nearly universal. Most teams can spin up a RESTful service in an afternoon and have it talking to a mobile app before brekkie the next day.

GraphQL flips that relationship. It offers a single endpoint that accepts queries describing exactly what the caller wants, returning only those fields in one round trip. The server defines a typed schema, the client sends a query, and the response mirrors the request shape. For teams building intricate product surfaces where multiple views share overlapping data, this can collapse the number of network calls dramatically.

The deeper difference lies in who owns the shape of the response. REST pushes that responsibility onto the server, which then evolves URLs and field names as the product grows. GraphQL gives the client more control, but the server still owns the schema and must defend it against expensive or malformed queries. Both models are valid. Neither is automatically superior.

When round-trip efficiency shapes the decision

Latency matters more in some markets than others. Australian users connecting over the NBN, 4G, or satellite services in regional Queensland understand that every kilobyte and every extra request costs something measurable. A mobile app that pulls a profile, then preferences, then notifications, then unread counts across three endpoints adds up to hundreds of milliseconds that users feel as jank.

GraphQL shines in this exact scenario. A single query can fetch everything a screen needs in one go, which is why companies with chatty interfaces, including news feeds, dashboards, and social products, often reach for it first. When Canva's engineering teams discuss their frontend data layer, the appeal of fewer round trips comes up repeatedly, because every saved millisecond compounds across millions of sessions.

REST can still win here with careful endpoint design. Aggregations, backend-for-frontend layers, or GraphQL-as-an-add-on over a REST core can deliver similar benefits without forcing the whole organisation onto a new paradigm. The trick is being honest about whether the optimisation is worth the operational cost for the screens that actually need it.

Schema design and long-term maintenance

GraphQL ships with a strongly typed schema as part of the contract. Tools can generate TypeScript types, validate queries at build time, and produce documentation automatically from the SDL files. For a team whose frontend and backend engineers sit in the same Slack channel, common at Atlassian-sized operations in Sydney, this tight feedback loop speeds up iteration.

REST relies on OpenAPI or similar specifications, which deliver similar benefits when the team commits to maintaining them. The downside is drift: hand-edited docs rot quickly, and many teams quietly abandon their spec files after a year or two. Without a guardrail, REST endpoints accumulate quirks. A field that returned a string for years now returns an integer, or a new optional field breaks older clients, and that debt compounds quietly.

The maintenance question is less about which is theoretically cleaner and more about which your team will actually keep tidy. GraphQL's centralised schema makes drift harder to hide. REST's decentralised URLs make it easier to ship fast but easier to ship inconsistency too.

Tooling, caching, and the developer experience

REST benefits from a quarter-century of HTTP infrastructure. CDN edge caching, ETag-based revalidation, conditional GET requests, and mature reverse proxies all work out of the box. For a public read-heavy endpoint serving Australian customers during business hours and American customers overnight, that ecosystem is hard to beat.

GraphQL's caching story is trickier. Because every query can be different, traditional HTTP caching rarely applies. Persisted queries, automatic persisted queries, and client-side caching libraries like Apollo or Relay pick up much of the slack, but each adds complexity. Teams building internal APIs for a single product often find this trade-off acceptable. Teams exposing APIs to thousands of external partners usually do not.

Developer ergonomics matter too. GraphQL Explorer tools let frontend engineers poke at the schema and copy ready-to-use queries into their code, which accelerates onboarding. REST tools like Postman and Insomnia offer similar value, but the schema-first culture of GraphQL gives newcomers a single starting point rather than a sprawl of endpoint documentation. On a tight team shipping a new product, that difference shows up in the first sprint.

Security, governance, and compliance realities

REST endpoints are easy to lock down one at a time with standard HTTP authentication, scopes, and rate limits. Most off-the-shelf API gateways ship with rules for protecting REST routes, and security teams have years of muscle memory for them. For a bank in Melbourne working under APRA's CPS 234 or a fintech operating under the Consumer Data Right, that maturity reduces audit friction.

GraphQL introduces a different threat surface. Because a single endpoint accepts arbitrary shapes, a careless query can be used to extract deeply nested data or trigger expensive joins. Persisted query allowlists, query cost analysis, depth limiting, and field-level authorisation all become necessary. None of these are showstoppers, but they demand engineering investment that a small team may struggle to justify.

Data residency is another consideration unique to this market. Australian regulations around health data, financial records, and government services often require storage within Australian borders. Both REST and GraphQL can be hosted in the AWS Sydney region or similar local infrastructure, but the choice of gateway, the location of caches, and the path of audit logs all need to line up with compliance obligations regardless of which paradigm you pick.

Scaling patterns and performance under load

GraphQL's famous N+1 problem hits teams who underestimate it. A query that returns a list of articles, each with an author, each with a social link, can translate to hundreds of separate database queries without proper data loaders. The DataLoader pattern, schema design discipline, and caching layers solve it, but only when the team understands them from day one.

REST scales in a more boring, more reliable way. Database indexing, query profiling, and connection pooling are well-understood patterns that senior engineers have applied for two decades. When a service needs predictable performance under heavy load, say a ticketing system handling a major concert presale or an ATO portal during end-of-financial-year lodgement, that predictability can outweigh the elegance of a query language.

Monitoring looks different too. REST metrics revolve around endpoint latency, error codes, and throughput. GraphQL metrics need to track query complexity, resolver timings, and field-level error rates. Both are solvable with modern observability tooling, but the mental model teams need to internalise is genuinely different.

Picking the right fit for real-world teams

The decision rarely stays binary. Plenty of Australian organisations run a hybrid: REST for system-to-system integrations and public partner APIs, GraphQL for their own frontend data layer. Afterpay's engineering blog has touched on this layered approach, and Atlassian's products mix both patterns depending on the consumer. Treating the choice as a spectrum rather than a verdict tends to produce saner architectures.

Start with the consumers. If the API exists for one product's frontend and that product is mobile-first, GraphQL's round-trip savings pay off quickly. If the API serves dozens of partner integrations, public documentation, and automated tooling, REST's maturity tends to win. If the answer is genuinely mixed, run both, REST at the edge, GraphQL as an aggregator over it, and let the patterns emerge from real usage rather than architectural preference.

The best teams revisit the question every couple of years anyway. Tools improve, schemas evolve, and what felt right during a quiet launch may creak under the weight of ten million monthly active users. Keeping the option open, documenting the trade-offs honestly, and refusing to treat either paradigm as a religion will serve a team far longer than any single decision made today.