MDAN is not a replacement for REST APIs. MDAN and REST APIs solve different problems at different layers.
That is the most important thing to say first.
REST APIs and MDAN operate at different layers.
REST APIs are a way to expose resources and operations over HTTP. MDAN is a way to keep the same interactive page readable and actionable for both humans and agents from the same source across different interfaces.
If you start by asking which one "wins," you usually end up comparing two things that are not trying to do the same job.
What REST APIs Are Good At
REST APIs are good at things like:
- exposing backend resources
- defining agent-facing operations
- supporting integrations between services
- giving clients stable programmatic access
That is still useful. In many systems, it is necessary.
MDAN does not try to erase that.
What MDAN Is Trying To Solve
MDAN is concerned with a different problem:
what happens to the page once interaction begins?
In many systems, the readable page is where people understand the workflow, but the real agent-facing contract lives somewhere else as an API plus extra documentation.
That creates a familiar split:
page for people
+ API for machines
+ docs to explain the API
When that split happens, the page often stops being the real interface. It becomes a human-facing shell.
MDAN is an attempt to reduce that gap by keeping the page itself useful for longer.
The Difference In One Sentence
The shortest useful distinction is this:
- a REST API exposes backend capabilities
- MDAN keeps the same interactive page usable across humans and agents from the same source
Those ideas can coexist.
Where They Fit Together
MDAN does not have to replace the backend shape of a system.
You can still have REST endpoints, internal services, auth flows, and storage APIs behind the scenes.
What changes is the role of the page.
Instead of treating the page as a rendered surface for people and the API as the only real machine contract, MDAN tries to let the page itself continue to expose:
- page context
- available inputs
- available actions
- a continuation surface for agents and other agent-facing clients
That is why MDAN is better thought of as a page-layer notation than as an API alternative.
A Small Example
Here is a minimal demo page:
---
title: "Demo"
---
# Demo
Leave a short message and refresh the block to see the latest entries.
<!-- mdan:block demo -->
You can still imagine ordinary HTTP handlers behind those actions.
The MDAN part is not "we no longer have routes."
The MDAN part is that the page remains a readable and actionable source instead of becoming only a rendered frontend sitting above an unrelated contract.
When REST APIs Are Still The Right Tool
REST APIs are still the right tool when you need:
- service-to-service integration
- stable backend contracts for many clients
- resource-oriented external APIs
- integration surfaces that are not page-centric at all
MDAN is not trying to displace those cases.
When MDAN Starts To Matter
MDAN starts to matter more when you are building:
- interactive docs
- internal tools
- CLI and web hybrids
- agent workflows
- products where humans and agents both need to continue from the same working surface
In those cases, keeping the page itself meaningful can be more valuable than splitting into separate surfaces immediately.
The Practical View
If you want the practical answer to "MDAN vs REST APIs," it is this:
REST APIs are still useful. MDAN is about not letting the page lose authority the moment interaction begins.
That is the boundary.
Related Reading
If you want the clearest definition of the notation itself, read What is MDAN?.
If you want to explore the project further: