Two ways to build a headless content system

Think of it like this: instead of needing to visit your office to see a document, the API creates photocopies that anyone with permission can access remotely. 

Key benefits 

• Speed to launch: You can have this running in minutes, not weeks. There's no custom development needed, just flip a switch in the settings, and you're operational. 

• Professional grade: This isn't a quick hack; it's enterprise software maintained by Umbraco's core team. It includes security, performance optimization, and all the features you'd expect from professional software. 

• Comprehensive data: The API provides everything about your content: when it was created, who updated it last, what images are attached, and how it relates to other content. It's thorough. 

The Trade-Offs 

• Verbose output: The API includes a lot of information—perhaps more than you actually need. It's like getting a full medical report when you just wanted to know if you need to take paracetamol. The extra data doesn't hurt, but it does mean larger file sizes. 

• Less control: The structure of the data is predetermined. You get what it gives you. For most businesses, this is perfectly fine, but if you need something very specific, you're somewhat limited. 

• Learning curve: While turning it on is simple, making full use of its advanced features requires understanding how it works. Not rocket science, but there's definitely learning involved. 

Approach two: Custom solution (The tailored approach) 

Building a custom solution is like hiring a tailor to make a bespoke suit. It takes more time and expertise, but the result fits your exact requirements perfectly. 

What it involves 

A custom solution means your development team writes specific code to deliver exactly the content you need, in exactly the format you want. Instead of getting everything, you define what matters and build accordingly. 

The technical implementation involves creating small programs (called controllers and services) that intercept requests for content and return customized responses. But you don't need to understand the mechanics -just the outcomes. 

Key benefits 

• Precision control: You decide what data is included and how it's structured. If you only need product names and prices, that's all you get—no extra baggage. 

• Minimal data transfer: Smaller data packages mean faster loading times, especially important for mobile users or customers with slower internet connections. In our testing, custom solutions typically deliver 70% less data than the ready-made API for the same content. 

• Integration flexibility: You can easily combine content from multiple sources. Need to mix Umbraco content with product data from your inventory system and search results from Algolia? A custom solution handles this seamlessly. 

• Unique business logic: Have specific rules about how content should behave? Custom solutions let you implement any business logic you need. 

The Trade-Offs 

• Development time: Building a custom solution takes longer. What might be minutes with the API becomes a little more than hours of development work. 

• Maintenance responsibility: You own the code, which means you're responsible for maintaining it, updating it, and fixing any issues. The ready-made API gets automatic updates from Umbraco. 

• Skill requirements: You need developers who understand both Umbraco and modern application development. 

• No preview functionality: Unlike the API, preview capabilities don't come built-in. If you need them, you'll have to build them yourself. 

Real-world example: California Shutters 

Let's look at a practical example where a custom solution made perfect sense.

California Shutters is an ecommerce business selling custom window treatments. Their website isn't just pulling from Umbraco - it's orchestrating data from multiple systems: 

• Umbraco CMS for marketing content and product descriptions 

• Struct PIM (Product Information Management) for detailed product specifications, pricing, and inventory 

• Algolia for powerful search functionality that helps customers find exactly what they need 

Their challenge? These three systems speak different languages and store data differently. The Content Delivery API works brilliantly for Umbraco content, but it can't talk to PIM systems or search engines. 

The custom solution 

true (the development team) built a custom layer that acts as a universal translator. When a customer visits the California Shutters website: 

1. The custom system pulls basic product information from Umbraco 

2. It enriches that with detailed specifications from Struct PIM 

3. It integrates real-time search and other functionality capabilities from Algolia 

4. It combines everything into one cohesive response 

The result? Customers see a seamless experience. They don't know (or care) that the product information came from Umbraco, the technical specifications from PIM, and the "customers also viewed" suggestions from Algolia. It all just works. 

Why this approach works 

For California Shutters, the Content Delivery API alone wouldn't have worked because: 

• They needed data from three different systems, not just Umbraco 

• Product specifications change frequently in the PIM system 

• They required a specific data structure that their e-commerce platform expected 

• Performance was critical—custom shutters are considered a purchase, and customers spend time browsing multiple products 

The custom solution delivered exactly what they needed: fast, integrated, and precise. Yes, it took longer to build initially, but it enabled a customer experience that wouldn't have been possible otherwise. 

The technical reality (simplified) 

Without getting too technical, here's what the custom solution does: when someone requests product information, instead of just returning raw Umbraco content, the system: 

• Identifies what content is needed 

• Fetches product details from the PIM system 

• Gets relevant data from Algolia 

• Combines everything intelligently 

• Returns a clean, unified package of information 

The development team wrote specific code (controllers and services) to handle this orchestration. It's like having a personal assistant who gathers information from multiple departments and presents you with a single, well-organized briefing. 

Making the right choice 

So which approach should you choose? Here's a practical guide. 

Choose the Content Delivery API (CDA) when: 

• You're building standard digital experiences: If you're creating a website, mobile app, or similar digital products that primarily use content from Umbraco, the CDA is perfect. 

• You need to launch quickly: When time-to-market matters and you don't have months for custom development, the CDA gets you operational immediately. 

• You operate internationally: Multi-language support and content management across regions are built-in and work brilliantly.

• You value long-term maintenance: The CDA is professionally maintained and automatically updated. You're not responsible for keeping it current. 

• Your team is small: If you don't have a dedicated development team, the CDA requires minimal technical expertise to implement. 

Choose a custom solution when: 

• You're integrating multiple systems: Like California Shutters, if you need to combine content from various sources (CMS, PIM, search engines, ERP systems), a custom API is the way to go. 

• Performance is critical: When every millisecond matters and you need the absolute minimum data transfer, custom solutions can be optimized precisely. 

• You have unique requirements: If your business processes are unusual or highly specific, custom development lets you implement exactly what you need. 

• You have development resources: Custom solutions require skilled developers for both initial build and ongoing maintenance. 

• You need specific data structures: If downstream systems (like your mobile app or digital displays) expect data in a very particular format, custom API gives you complete control. 

The hybrid approach 

Here's something many businesses don't consider: you can use both approaches simultaneously. 

You might use: 

• The Content Delivery API for standard content (articles, pages, basic product info) 

• Custom endpoints for specialized functionality (product configurators, real-time inventory, personalized recommendations) 

• Integration layers that combine API data with external systems 

This hybrid approach gives you the speed and convenience of the API where appropriate, with the precision of custom solutions where needed. 

Cost considerations 

Let's talk about the elephant in the room: budget. 

Content Delivery API Costs: 

• Essentially free (included with Umbraco) 

• Minimal development time (hours, not weeks) 

• Low ongoing maintenance (handled by Umbraco) 

• Total Cost of Ownership: Very low 

Custom solution costs: 

• Development time (could be several weeks) 

• Ongoing maintenance and updates 

• Requires skilled developers 

• Testing and quality assurance 

• Total Cost of Ownership: Higher 

Performance and user experience 

From a customer's perspective, the difference between these approaches is often invisible—if done well. 

The Content Delivery API typically delivers content in 200-500 milliseconds, which feels instant to users. Custom solutions can be faster (100-300 milliseconds) because they're optimized for specific use cases, but the difference is barely perceptible. 

Where you do notice the difference is in data transfer size. If your customers are on mobile networks or in areas with slower internet, a custom solution that delivers 70% less data can significantly improve their experience. 

Making the decision: A framework 

Ask yourself these questions: 

1) Are we only using Umbraco for content? 

Yes → CDA probably works fine 

No → Consider custom API 

2) Do we need to integrate with other systems? 

No → CDA is simpler 

Yes → Custom API might be necessary 

3) How quickly do we need to launch? 

Urgently → CDA 

We have time → Either works 

4) Is our use case standard or unusual? 

Standard → CDA 

Unusual → Custom API 

What's our budget? 

Limited → CDA 

Flexible → Consider both based on needs 

Conclusion 

Both approaches to headless content management have their place. The Content Delivery API is brilliant for most scenarios—it's fast to implement, professionally maintained, and handles the majority of use cases beautifully. 

Custom API solutions shine when you have complex integration needs, unique requirements, or specific performance demands. Projects like California Shutters demonstrate how custom development enables experiences that wouldn't be possible with off-the-shelf solutions. 

The key is an honest assessment of your needs. Don't build custom because it sounds impressive. Don't use the CDA just because it's easier if it won't actually solve your problem. 

Start by clearly defining what you're trying to achieve. If the Content Delivery API can get you there, use it- you'll save time and money. If you need something more sophisticated, invest in custom development. 

And remember: you're not locked into one approach forever. Many businesses start with the CDA for speed, then gradually add custom components as specific needs emerge. It's evolution, not revolution. 

The future of digital content is headless, and Umbraco gives you the flexibility to implement it in whatever way serves your business best. That's the real power - choice based on actual needs, not technical limitations.