Resource identification
Everything is identified by URI. app://self/user points to the intent 'I want user information,' while How (MySQL or Redis, how to fetch) is hidden from the application.
Web principles
The most time-tested technology as the backbone of design.
URI, uniform interface, hypermedia. REST is a battle-tested design that has supported the Web for a quarter century. BEAR.Sunday makes it a constraint not just for external APIs but for the entire interior of your application. Not because it's new—but because its correctness endures.
Uniform interface
The Web was right from the start.
REST is not new technology. The concept of a collection of resources connected by links has been part of the Web since the 1990s. At its core, the uniform interface refers not to methods alone, but to four constraints. BEAR.Sunday applies these constraints consistently—not just to external APIs, but to the interior of the application as well.
Manipulation through representations
Clients don't touch resources directly—they operate through representations. State is separated from representation; the same state can yield HTML, JSON, HAL, and CLI.
Self-descriptive messages
Method safety, idempotency, media types, and status codes carry meaning in the message itself. Recipients can interpret the message without guessing hidden context.
Hypermedia (HATEOAS)
Resources present what can be done next (affordances) as links. Clients navigate application state by following the offered links rather than guessing the next transition.
Method semantics
Six verbs, each carrying meaning.
At the heart of self-descriptive messages lies method semantics. REST methods are not CRUD on tables—they are operations on application state. Each carries a property of being either safe (not changing state) or idempotent (same result regardless of repetition). These properties are not mere convention—they become the rationale that pays off later. GET is safe, so it can be freely cached and freely invoked by AI. State-changing operations are handled differently based on idempotency. The same semantics apply in both caching strategy and AI safety design.
| Method | Safe | Idempotent | Meaning |
|---|---|---|---|
| GET | Safe | Idempotent | Reads state. Does not change the resource. |
| POST | — | — | Changes state. Not idempotent; repeated execution may yield different results. |
| PUT | — | Idempotent | Places the entire representation at the URI (creates if absent). Same result every time. |
| PATCH | — | — | Applies a diff. |
| DELETE | — | Idempotent | Deletes. Idempotent like PUT. |
| OPTIONS | Safe | Idempotent | Inquires about required parameters and responses. |
Hypermedia
Clients follow links—they don't guess.
In hypermedia, resources present not just state but also what operations are available next (affordances). In HAL, _links serves this role, with rel indicating the type of relationship. Clients follow the links that resources offer rather than guessing what they can do next.
#[Embed] goes further. It doesn't embed the result of a resource—it embeds the request to a resource, i.e., the relationship between resources itself. This distinction later pays off in the form of parallel execution.
{
"_links": {
"self": { "href": "/article/42" },
"author": { "href": "/profile/7" },
"next": { "href": "/article/43" }
},
"_embedded": {
"comments": { "_links": { "self": { "href": "/article/42/comments" } } }
},
"title": "Because Everything is a Resource"
}Browsable, headless REST
An explorable, self-describing application from the root.
Resources written in HAL function as a headless REST application. Like navigating a website, you can reach every resource simply by following links from the root. The API describes itself; documentation can be discovered from the API itself. Humans, console curl commands, and AI agents all navigate the same way.
Self-descriptive
Links, schemas, and documentation are derived from the resource itself. Prevents specification and implementation from existing separately and drifting apart.
Explorable
Follow links from the root to related resources. You don't need to load the whole picture at once—just trace the necessary relationships in order.
Testable around state
Because representation and state are separated, you can directly inspect body, headers, and links even for HTML representations. No need to parse rendered strings and guess results.
Why the classic still wins
The classic had already prepared for a modernity no one foresaw.
Declaring relationships alone separates intent (What) from execution (How). That's why embedded resources can be fetched in parallel, resources become AI instruments as-is, multiple representations emerge from the same meaning, and evolution can continue with backward compatibility intact. These aren't bolt-on features—they are the result of accepting the Web's original nature as a design constraint.
Start with one resource