[Case Study] Transforming ABN AMRO’s API Documentation with Docuwiz
What if ABN AMRO Bank approached Docuwiz with the challenge of developer onboarding for their Account Information APIs
Executive Summary
This case study explores how Docuwiz would transform ABN AMRO’s existing API documentation into an interactive, developer experience that accelerates integration.
While analysing developer onboarding for their Account Information PSD2 APIs, we found a problem:
The Challenge
ABN AMRO’s developer portal (developer.abnamro.com), although thorough and technically correct, the traditional format presents several friction points that high cognitive load and increase time-to-first-success.
About Docuwiz
Docuwiz is an interactive API documentation platform that transforms traditional specification-driven docs into dynamic workspaces. Rather than treating documentation as a static reference, Docuwiz creates an environment where developers can explore, configure, and test APIs directly within the documentation itself, eliminating the gap between reading about an API and actually using it.
API Guides
Written guides are critical to good API adoption; they provide context, explain intent, and help developers understand why an API works the way it does, not just how to call it.
Docuwiz treats the guide as the natural starting point, making it the landing page and allowing users to absorb the narrative first, while a clear side panel keeps all related endpoints visible and accessible at all times.
In contrast, the current ABN AMRO approach fragments the same guide across multiple pages, forcing users to jump between sections and locations. That constant navigation increases cognitive load.
API Documentation
Current State
ABN AMRO’s current documentation for the getConsentInfo endpoint follows the conventional specification-driven model. Developers encounter:
Dense parameter tables requiring careful reading and interpretation
Separated sections for headers, request structure, and responses
Text-heavy descriptions of constraints, enums, and required fields
A mental translation layer between documentation and implementation
This approach optimizes for completeness. Every detail is present, every parameter documented, every response code explained. However, developers must actively decode this information, jumping between sections and mentally simulating requests before writing a single line of code.
The Transformation
Docuwiz reimagines the same endpoint as an interactive workspace where the entire API flow exists in one connected view:
Host selection becomes a dropdown, not a text field to copy
Headers are editable inline with environment-aware defaults
Request parameters are configured through interactive controls
Responses are explorable with instant schema-to-example switching
Examples appear contextually where decisions are being made
The documentation becomes the API’s interface during the learning phase.
Why This Matters
Developers understand the endpoint faster because they’re interacting with it, not interpreting it. First calls happen sooner because the path from learning to doing is shorter. Fewer assumptions are made about inputs and responses because the interface constrains choices to valid options.
The gap between reading and running the API disappears entirely.
2. One API, Two Ways to Understand It
Great API documentation recognizes that backend engineers, frontend developers, and integration partners all approach APIs differently. A single organizational structure cannot serve all audiences equally well.
View by Path: Understanding API Architecture
ABN AMRO’s current path-based organization (/v2/consentinfo/{consentId}, /v2/accounts, etc.) reveals the API’s structural design at a glance.
This view is invaluable for:
API designers reviewing architectural consistency
Backend engineers understand resource modeling and hierarchy
Platform teams conducting governance reviews and debugging
Path-based organization answers the question: “How is this API built?”
View by Tags: Finding Capabilities Quickly
Docuwiz adds tag-based organization that groups endpoints by business capability. Developers can jump directly to what they’re trying to accomplish.
This view serves:
Frontend developers building specific features
Partners integrating particular capabilities
First-time users discovering what the API can do
Tag-based organization answers: “What can I do with this API?”
The Advantage:
The documentation adapts to different mental models without content duplication. Teams move faster, onboarding improves, and the API becomes simultaneously easier to understand and easier to trust.
3. Turning Written Rules into Interactions
The Problem with Text-Heavy Constraints (Current State)
Traditional API documentation relies heavily on prose to communicate rules:
“The
consentIdparameter must be a valid UUID v4”“Status values are:
received,valid,revokedByPsu,expired,terminatedByTpp““The
X-Request-IDheader is required and must be unique per request.”
Developers must read these descriptions, remember the constraints, and manually ensure compliance when crafting requests. This cognitive overhead is where mistakes happen and frustration builds.
Encoding Constraints in UI (The Docuwiz Approach )
Docuwiz transforms textual rules into interface affordances:
Enum values become dropdowns showing only valid choices
Required fields are visually distinct and enforced by the interface
Format constraints (UUIDs, dates, etc.) are validated in real-time
Invalid inputs are prevented by design, not caught after the fact
Impact on Developer Experience
Users no longer need to remember allowed values or flip back to descriptions. The interface presents only valid choices, making the API feel simpler without changing the underlying complexity.
The result is time-to-first-success reduces. Interactive controls create confidence through visual feedback developers can trust that their selections, eliminating the second-guessing that plagues text-heavy documentation.
4. Response Documentation
The Traditional Response Layout (Current State)
ABN AMRO’s current documentation presents response schemas as dense information blocks. To understand what a successful getConsentInfo response looks like, developers must:
Scan through field names, types, and descriptions
Note which fields are required vs. optional
Review enum values for status fields
Mentally assemble how all these pieces combine
Imagine what actual data would look like
It’s technically complete but cognitively expensive.
With Docuwiz: Schema and Examples as Side by Side
Docuwiz separates structure from understanding by offering instant switching between:
Schema View : The exact contract with types, constraints, and required fields
Example View : A realistic response showing actual data formats and structures
This seemingly simple change removes substantial friction. Instead of decoding abstract schemas, developers see responses as they’ll actually appear in production usage.
Measurable Benefits
Examples eliminate guesswork about how fields relate to each other and what real values look like.
Seeing actual date formats, nested object structures, and enum values in context reduces incorrect assumptions that lead to parsing errors.
New developers understand responses without requiring deep knowledge of PSD2 specifications or banking protocols.
5. Documentation as Product Experience
Traditional Model: Documentation describes the rules and hopes developers follow them correctly.
Docuwiz Model: Documentation actively guides developers toward successful API calls through interactive design.
This shift aligns documentation with product experience. When docs behave like well-designed products, responsive, intuitive, forgiving of exploration, they reinforce the perception that the API itself is reliable, well-architected, and production-ready.
Ready to level up your docs as code workflow with built-in AI assistance?
Conclusion
ABN AMRO’s API documentation is technically sound and comprehensive. However, in an era where APIs are products rather than mere technical interfaces, documentation must evolve beyond passive reference materials.
The result is documentation that actively drives adoption, reduces friction, and builds trust in ABN AMRO’s API platform.
Great API documentation doesn’t force everyone to think the same way. It meets developers where they are, guides them toward success, and gets out of the way as quickly as possible.
That’s the difference Docuwiz makes.
For more information about transforming your API documentation into an interactive developer workspace, visit docuwiz or contact our team for a customized demonstration using your existing OpenAPI specifications.