Engineering Around Bureaucracy: Surviving the ARGE Data Exchange Format

Introduction

The ARGE HeiWaKo specification was introduced to standardize energy data exchange between Property Managers (PM) and Metering Service Companies (MSC), in line with the EU’s Energy Efficiency Directive (EED). The goal was clear: deliver consistent consumption data in a structured, machine-readable way.

As a concept, it’s necessary. As a specification? It’s a cautionary tale of what happens when technical standards are built without engineers at the table.

The Problem with ARGE’s API Specification

While the underlying intent of ARGE is valid, its implementation is riddled with architectural and engineering failures that break production systems, waste developer hours, and ultimately delay compliance.

Let’s examine a few:

1. Inconsistent Routing Design

The original endpoint was structured like this:

/eedbillingunits?pmnumber=12345678

clean, logical, and query-driven.

Later endpoints suddenly changed to:

/billingunits/{billingunit}/consumptions/periods

/billingunits/{billingunit}/consumptions/periods/{period}

This shift implies either two different teams — or two different time periods behind the spec. It’s not wrong to use path parameters in general, but here it introduces inconsistency with functional consequences.

Let’s test this with a real-world use case.

If a customer identifies their billing unit as 12345678, then:

/eedbillingunits?pmnumber=12345678 or

/billingunits/12345678/consumptions/periods/2025

Both work fine. But what if the billing unit is AB/02/UG? Then:

/eedbillingunits?pmnumber=/AB/02/UG or

/billingunits/AB/02/UG/consumptions/periods/2025

The first still works.

The second? Breaks routing in every modern framework.

• Fastify? Fails.
• Express? Fails.
• Flask, Django, ASP.NET? Also fail — unless you write complex escape logic or use fragile wildcards.

The spec moved from a working design to a broken one — and offered no guidance for escaping, encoding, or alternate formats. Worse still, it assumes customers will somehow handle this on their own.

What do you tell them?

“Please base64-encode your identifier before sending it to our state-compliant endpoint”?

That’s not serious engineering. That’s spec-driven sabotage.

2. Lack of Versioning and Forward Planning

The ARGE spec lacks any clear versioning scheme. As of now:

• There’s no /v1/ prefix or compatibility declaration.
• Breaking changes (like routing structure) are introduced mid-spec
• Implementers must reverse-engineer changes or rely on hearsay.

This introduces compliance drift: different vendors support different behaviours under the same “standard.”

3. Identifiers Not Fit for URLs

The primary key used in routing — external_reference_id (a.k.a. pmnumber) is not URL-safe:

• It often includes /, which must be escaped
• Some systems include spaces or localized formatting
• The spec does not require URL encoding or provide base64 support

The result? A path-driven format where the identifier breaks the path.

You couldn’t design a more self-defeating API pattern if you tried.

The Cost to Implementers

These flaws aren’t theoretical. Here’s what implementers have had to do:

• Write manual base64 encoding/decoding wrappers for all identifiers
• Use wildcard routers with fragile path splitting logic
• Build test harnesses just to figure out what the spec meant
• Reverse-engineer which endpoints expect query params vs. path params
• Develop defensive routing strategies just to comply with a government document

None of this is product value. None of it improves security, performance, or maintainability.
This is bureaucratic overhead disguised as API design as us as developers must alter the specification thus deviate from the standard.

What Could Have Been Done Better

• Use query parameters for identifiers; they’re safe, flexible, and extensible
• Introduce versioning in all paths (/v1/billingunits/...)
• Offer encoding guidelines for unsafe characters (not needed to query parameters)
• Validate the spec against real-world data before ratification (test user behavioural based input)
• Include practising SENIOR backend engineers in the working group

Standards need to reflect how the web actually works & how property management actually works not how a committee thinks it should.

Recommendations for Implementers

If you’re stuck implementing ARGE, here’s your best path forward (and yes, it means adjusting the spec):

1. Move identifiers into query parameters.
2. /billingunits/consumptions/periods?pmnumber=AB/02/UG&period=2025
3. Document every workaround you use (you’ll need it again for v2)

Final Words: We Deserve Better Specs

Open standards are powerful — but only if they’re usable.

ARGE’s current spec prioritizes surface-level REST aesthetics over practical developer workflows. In doing so, it fails the engineers who have to implement it, and it delays the very energy efficiency goals it was meant to support.

We can — and must — do better.

Future revisions must:

• Involve practising developers from the start
• Validate decisions in actual web environments
• Prioritize clarity and compatibility over dogma

Until then, we’ll keep writing wrappers to make broken specs work — not because they’re right, but because we have no choice.

And that means more time, more money, and more waste — in a spec designed to prevent exactly that.