MDSN is not a replacement for REST APIs.
That is the most important thing to say first.
REST APIs and MDSN operate at different layers.
REST APIs are a way to expose resources and operations over HTTP. MDSN is a way to keep an interactive page readable, actionable, and continuable 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 machine-facing operations
- supporting integrations between services
- giving clients stable programmatic access
That is still useful. In many systems, it is necessary.
MDSN does not try to erase that.
What MDSN Is Trying To Solve
MDSN 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 machine-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.
MDSN 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
- MDSN keeps an interactive page usable across humans and agents from the same source
Those ideas can coexist.
Where They Fit Together
MDSN 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, MDSN tries to let the page itself continue to expose:
- page context
- available inputs
- available actions
- a continuation surface for machine-facing clients
That is why MDSN is better thought of as a page-layer notation than as an API alternative.
A Small Example
Here is a minimal guestbook page:
---
title: "Guestbook"
---
# Guestbook
Leave a short message and refresh the block to see the latest entries.
<!-- mdsn:block guestbook -->
You can still imagine ordinary HTTP handlers behind those actions.
The MDSN part is not "we no longer have routes."
The MDSN 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
MDSN is not trying to displace those cases.
When MDSN Starts To Matter
MDSN starts to matter more when you are building:
- interactive docs
- internal tools
- CLI and web hybrids
- agent workflows
- products where humans and machine-facing clients 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 "MDSN vs REST APIs," it is this:
REST APIs are still useful. MDSN is about not letting the page lose authority the moment interaction begins.
That is the boundary.
If you want to explore the project further: