Umbraco Delivery API vs. The New GraphQL Package: Choosing the Right Headless Strategy
Introduction
Headless Umbraco just got more interesting. For years, the Content Delivery API was the default (and often only) route for teams decoupling their front end from Umbraco's rendering pipeline. At present, the GraphQL framework has developed sufficiently and this provides developers an opportunity to make a right choice that is not only technical but also strategic in order to enhance the flexibility of the queries, increase the speed of the team and make the processes efficient in the long term.
The issue here is not about which one is better, but about which one works for you.
The graph below shows how the two systems relate in terms of five key decision points that you should consider in your headless Umbraco project.
1. Query Flexibility: Fixed Shape vs. Client-Defined Shape
The Delivery API returns content in a predictable, predefined JSON structure. Great for consistency, limiting when your front end needs something different per view.
GET /umbraco/delivery/api/v2/content/item/{id}?fields=properties[title,summary]
The GraphQL package flips this: the client defines exactly what shape it wants, nesting relations in a single request.
GraphQl
query {
allContent(contentType: "article") {
items {
title
summary
author {
name
bio
}
}
}
}
Benefits
- GraphQL eliminates over-fetching and under-fetching
- Delivery API is faster to reason about for simple, flat content types
- GraphQL reduces the number of round trips for nested/relational content
2. Setup and Learning Curve
The Delivery API ships with Umbraco and needs minimal configuration: enable it, set your API key, and you're querying within minutes. The GraphQL package requires installation, schema configuration, and a mental shift for teams unfamiliar with GraphQL's type system.
dotnet add package Umbraco.Community.GraphQL
Benefits
- Delivery API is the faster path for small teams or MVPs
- GraphQL front-loads complexity but pays off at scale
- Umbraco's native tooling favors Delivery API for out-of-the-box projects
3. Performance at Scale
For simple content trees, both perform comparably. Where it diverges is complex, relationship-heavy content models. GraphQL's single-request resolution becomes a real performance win once you're stitching together five or six content types per page.
GraphQl
query {
page(url: "/products/widget") {
title
relatedProducts {
title
price
}
reviews {
rating
comment
}
}
}
Benefits
- GraphQL reduces waterfall requests for composite pages
- Delivery API's caching model is simpler to reason about and tune
- Fewer endpoints in GraphQL means fewer cache invalidation edge cases
4. Developer Experience and Tooling
With GraphQL, tools such as introspection, GraphiQL/Playground, type safety, and IDE support are embedded in the framework. The Delivery API relies on Swagger/OpenAPI documentation in addition to manual distinct endpoint discovery.
GraphQl
{
__schema {
types {
name
}
}
}
Benefits
- GraphQL's introspection speeds up front-end onboarding
- Delivery API's OpenAPI spec integrates more easily with existing REST tooling
- Strong typing in GraphQL catches shape mismatches before runtime
5. Long-Term Maintainability
This is where the strategic call really lives. Delivery API changes tend to ripple across every consuming front end when content models shift. GraphQL's schema-first approach isolates those changes front ends request what they need, and schema evolution can be additive rather than breaking.
GraphQl
type Article {
title: String!
summary: String
publishedDate: DateTime
}
Benefits
- GraphQL schemas act as a contract, reducing breaking changes downstream
- Delivery API is easier to version predictably (v1, v2 endpoints)
- Teams with multiple front ends (web, app, kiosk) benefit more from GraphQL's shared schema
Best Practices for Choosing
- Default to Delivery API for single front-end projects with straightforward content models and tight timelines.
- Choose GraphQL when you're powering multiple front ends (web, mobile, partner integrations) off one Umbraco instance.
- Audit your content relationships first deeply nested or relational models favor GraphQL's single-query resolution.
- Factor in team familiarity GraphQL's learning curve is real, and rushed adoption slows early sprints.
- Don't rule out a hybrid approach some teams use Delivery API for simple pages and GraphQL for complex, composite views.
- Revisit caching strategy regardless of choice both need deliberate cache invalidation planning as content scales.
Conclusion
There's no universally "right" answer between the Delivery API and the GraphQL package, only the right answer for your project's shape, team, and roadmap. If you're shipping a single front end fast, the Delivery API's simplicity is hard to beat. If you're building for multiple channels or already fighting over-fetching problems, the GraphQL package's precision starts paying dividends almost immediately.
What matters most is making this decision early and deliberately, rather than defaulting to whichever API your team happened to try first. Headless architecture decisions compound over time the flexibility (or friction) you build in now is what your front-end teams will live with for years.
Choosing between the Delivery API and GraphQL isn't about picking a winner, it's about picking the tool that matches how your content actually needs to move.
Related Blogs
Read More
Read More
Read More