Web principles

いちばん枯れた技術を、設計の背骨にする。

URI、統一インターフェース、ハイパーメディア。RESTは四半世紀にわたってWebを支えてきた、枯れた設計です。BEAR.Sundayはそれを外部APIだけでなく、アプリケーションの内側全体の制約にします。新しさではなく、正しさが残っているからです。

Uniform interface

Webは、最初から正しかった。

RESTは新しい技術ではありません。リンクでつながるリソースの集合という考え方は、 Webが1990年代から持っていたものです。その核にある統一インターフェース(uniform interface)は、メソッドのことではなく、次の4つの制約を指します。BEAR.Sundayは、この制約を外部APIに限らず、アプリケーションの内側にも一貫して適用します。

リソースの識別

すべてをURIで識別します。app://self/user は「ユーザー情報が欲しい」という意図を指し、MySQLかRedisか、どう取得するか(How)はアプリケーションから隠れています。

表現を通じた操作

クライアントはリソースを直接いじらず、表現(representation)を介して操作します。状態は表現と分離され、同じ状態からHTML・JSON・HAL・CLIが生まれます。

自己記述メッセージ

メソッドの安全性・冪等性、メディアタイプ、ステータスコードが、メッセージ自身に意味を載せます。受け手は隠れた文脈を推測せず、メッセージだけで解釈できます。

ハイパーメディア(HATEOAS)

リソースは次にできること(affordance)をリンクとして差し出します。クライアントは次の遷移を推測せず、差し出されたリンクをたどってアプリケーションの状態を進めます。

Method semantics

6つの動詞に、意味が宿っている。

自己記述メッセージの中心が、メソッドの意味論です。RESTのメソッドは、テーブルのCRUDではなく、アプリケーションの状態に対する操作です。それぞれが「安全(状態を変えない)」か「冪等(何度実行しても同じ)」かという性質を持ちます。この性質は単なる作法ではなく、後で効く根拠になります。GETは安全だから自由にキャッシュでき、AIにも自由に呼ばせられる。状態を変える操作は、冪等性に応じて扱いを変える。同じ意味論が、キャッシュ戦略でもAIの安全設計でも使われます。

Method	Safe	Idempotent	意味
GET	安全	冪等	状態を読む。リソースを変えない。
POST	—	—	状態を変える操作。冪等でなく、連続実行で結果が変わりうる。
PUT	—	冪等	状態を指定する操作。冪等で、連続実行でも結果は同じ。
PATCH	—	—	差分を適用する。
DELETE	—	冪等	削除する。PUTと同じく冪等。
OPTIONS	安全	冪等	必要な引数と応答を問い合わせる。

Hypermedia

クライアントは、推測せずリンクをたどる。

ハイパーメディアでは、リソースは状態だけでなく、次にどんな操作ができるか(affordance)を自分で提示します。HAL では _links がそれにあたり、rel が関係の種類を示します。クライアントは次に何ができるかを推測せず、リソースが差し出すリンクをたどります。

#[Embed] はさらに踏み込みます。これはリソースの「結果」を埋め込むのではなく、リソースへの「リクエスト」、つまりリソース間の関係そのものを宣言します。この違いが、後で並列実行という形で効いてきます。

{
  "_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

ルートから辿れる、説明可能なアプリケーション。

HALで書かれたリソース群は、ヘッドレスなREST アプリケーションとして機能します。 Webサイトを巡るように、ルートからリンクをたどるだけで、すべてのリソースへ到達できます。 APIが自分自身を説明し、ドキュメントをAPI自身から見つけられます。人間も、コンソールのcurlも、そしてAIエージェントも、同じ辿り方をします。

自己記述的

リンク、スキーマ、ドキュメントがリソース自身から導かれます。仕様と実装が別々に存在し、ずれていくことを防ぎます。

探索可能

ルートのリンクから関連リソースへ辿れます。全体像を一度に読み込ませなくても、必要な関係だけを順にたどれます。

状態を中心にテストできる

表現と状態が分かれているため、HTML表現でもbody、headers、linksを直接確認できます。レンダリング後の文字列を解析して結果を推測する必要がありません。

Why the classic still wins

古典が、まだ知らなかった現代を用意していた。

関係を宣言するという一点から、意図(What)と実行(How)が分かれます。だから、埋め込みリソースは並列に取得でき、リソースはそのままAIの道具になり、同じ意味から複数の表現が生まれ、後方互換を保ったまま進化できます。これらは後付けの機能ではなく、 Webが最初から持っていた性質を、設計の制約として引き受けた結果です。

並列性として見る AIの道具として見る

Start with one resource

まずは小さく作り、構造を残す。

Quick Start llms-full.txt