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):
- Move identifiers into query parameters.
/billingunits/consumptions/periods?pmnumber=AB/02/UG&period=2025
- 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.
