【コード哲学エッセイ】 公開 API は機能じゃなく約束の窓だ

内部と外部の境界を守る設計

七月の朝、エアコンの音だけが部屋に残っている。
Slack に小さな通知が届く。

「連携先の画面で、ユーザー名が出なくなりました」

僕はすぐにログを開いた。
サーバーは生きている。
ステータスコードも 200。
壊れているのは、見えないところだけだった。

エンドポイントを増やせば進んでいると思っていた

若い頃、API 設計という言葉を聞くと、頭のなかではこう翻訳されていました。

機能を外に出す作業。

医療系の現場でも Web の案件でも、よく似た光景がありました。
テーブルの列をそのまま JSON にする。
JOIN した結果を、とりあえず返す。
「あとで整える」と口にしながら、内部の地図を外に丸ごと渡す。

当時の僕にとって、公開 API は倉庫の搬出口でした。
中に何があるかは、知っている人だけが知っていればいい。
外から見えるのは、とりあえず出てきた箱。

速い。楽だ。今日のタスクは減る。

その代わり、約束は生まれない。
「この形で返す」と書いていないから、変えても罪悪感が薄い。
変えたのは自分だけだと思い込める。

内部の部屋をそのまま窓にしてしまう

フリーランスになって数年、小さな SaaS の API を触ったことがあります。
ユーザー一覧を返すエンドポイント。
実装は単純で、ORM の結果をそのまま res.json() していた。

社内の管理画面では問題にならない。
同じチームが、同じ頭のなかの辞書を共有しているからだ。

ところが、外部の連携先がついた。
相手は僕の DB を知らない。
知る必要もない。

あるリリースで、表示名のフィールドが変わった。
userName から displayName へ。
互換のため、しばらく両方返すつもりだった。

内部の話では、そう言い切れていた。
けれど、レスポンスの形に約束が書かれていなかった。
型も薄かった。
ドキュメントも古かった。

相手の画面だけ、名前が消えた。
エラーは出ない。
ログも静かだ。
約束が更新されていない窓だけが、空を映していた。

あの夜、僕は六月のエッセイを思い出した。
型は約束の可視化だ、と書いたあの話だ。
API のレスポンスにも、同じ構造があった。

窓は家のすべてを見せるためじゃない

いまの僕は、公開 API をこう捉えています。

内部を外に運ぶ穴ではなく、未来の利用者と交わす約束の窓だ。

家の窓は、壁をなくすためではない。
外の光を取り込み、中の様子を選んで見せるための装置だ。
全部晒す窓は、部屋ではなく展示場になる。

README を玄関だと書いたことがある。
API は、その家の外壁に開いた窓に近いと思う。

玄関で礼儀を伝え、窓で景色を渡す。
奥の間の荷物の置き方まで、客人に知らせる必要はない。

機能一覧と約束一覧は違う

仕様書を書くとき、僕は昔よくこう並べていた。

📍 ユーザーを取得する
📍 ユーザーを更新する
📍 プロジェクトを削除する

できることのリスト。
それは機能の棚卸しにはなる。
けれど、利用者が本当に知りたいのは、たいていもう一歩先だ。

どの形で返すか。
何が変わったら、自分のコードが壊れるか。
変わるとき、いつ・どう知らせるか。

ここまで書いて初めて、機能は約束になる。

個人開発のポートフォリオ API を /api/v1 にしたのも、同じ感覚だった。
バージョンは飾りじゃない。
この窓の枠は、しばらく変えないという宣言だ。

Hono で API を組むときも、公開向けと管理向けで積み木を変える。
認証の層を、全部のルートに載せない。
それはセキュリティの話だけじゃない。
外から見える窓と、内側だけの扉を混ぜないためだ。

早さのために境界を飛ばした代償

正直に言うと、境界を引く作業は遅い。
DTO を一つ足すだけでも、ファイルは増える。
「内部の形で十分」と感じる日も、まだある。

それでも、境界を飛ばしたときの代償は、だいたい他人の朝にやってくる。

自分のフロントなら、同じリポジトリで直せる。
連携先の担当者は、僕の頭のなかにはいない。
彼らにとって、壊れた窓は突然の天気の変化だ。
曇ったのか、雨なのか、説明がなければ分からない。

設定値を境界だと書いた六月。
型を約束の地図だと書いた六月。
その延長に API の窓がある。

隠すための壁でも、機能を並べる棚でもない。
責任が外に渡る瞬間に、線を引く場所だ。

窓を開ける前に僕が置く三つの問い

エンドポイントを増やす前に、僕は三つだけ問います。

このレスポンスは、内部の都合か、外への約束か。
形を変えるとき、誰が気づける仕組みがあるか。
いま見せている窓は、本当に外に必要な景色か。

答えがはっきりしないものは、まだ公開しなくていいのかもしれない。
社内だけで使うなら、扉の内側に置けばいい。
三回、同じ形の変更が来たら、窓の枠を太くする。
六月に書いた DRY の話と、同じ温度だ。

// 外に見せる約束: 一覧で必要な形だけに絞る
type PublicUser = {
  id: string;
  displayName: string;
};

displayName の一行が、あの朝の空欄を未来の自分から遠ざけてくれる。
窓は、世界のすべてを映す必要はない。
外の人が立ち止まらない景色だけ、選んで渡せばいい。

壊れたあとに責めるより、 先に書く

約束の窓を守るのは、最初から完璧な API を設計することじゃない。
壊れたあとに、約束を言葉に戻すことでもある。

変更ログを残す。
互換期間を決める。
「ここから先は変わります」と、窓の外に小さな札を貼る。

エラーを案内役だと書いた二月の自分に、今でも助けられている。
API も同じだ。
404 や 400 は、敵じゃない。
約束が通じなかった場所を教えてくれる。

責めるより先に、地図を更新する。
それが、外の人への礼儀だと思うようになりました。

七月のエディタの前で僕が思うこと

下半期が始まる七月、新しい機能を出したくなる季節でもある。
とりあえず公開したが、きれいに聞こえるとき。

そのたび、僕は昔の自分に声をかけます。

「これは機能を増やしているのか
　約束の窓を開けているのか」

前者なら、一度立ち止まる。
後者なら、枠の形を丁寧に決める。

公開 API は、倉庫の搬出口じゃない。
外の誰かが、まだ見ぬ朝のために残す窓だ。

同じように、内部の地図をそのまま外に渡してしまった誰かに届けばうれしいです。

ひとりごと

エンドポイントを並べた仕様書を、昔は達成感で閉じていました。
増えた数だけが、進歩に見えていたのかもしれません。

いまは、小さなレスポンス型を一つ書くほうが、胸の奥が静かになることがある。
それは遅さじゃない。
外の人の時間を、先に守っている感覚に近い。

七月の暑さのなかでも、窓の外に届く空気を想像しながら、線を引いていきたいです。

Substack はじめました

ここまで読んでくださり、ありがとうございました。

X では短い言葉で、note では整理した文章で発信していますが、Substack では、もっと途中経過の思考や削りきらなかった葛藤、技術者として日々考えていることを書いています。

もし興味があれば、覗いてみてください。

会社員（元システムエンジニア）からフリーランスとなり、
15 年目に突入しました。

納期と障害対応に追われる毎日の中で、
「もっと自由に、もっと本質的にものづくりがしたい」
そう思ったのが独立のきっかけです。

現在は、技術と文章を軸に、
仕事がラクになる仕組みや続けられる働き方を発信しています。

あわせて読みたい

▼ 約束を形にする話として並べて読みたいときに

API の窓にも、型という地図がある。
六月のエッセイと、同じ約束の語彙でつながります。

▼ 境界を引く設計のもう一本の線として

隠す場所と渡す場所。
責任が切り替わる線の引き方を、別の角度から描いています。

▼ 外から入る第一印象として

玄関と窓。
外の人を迷わせない、出迎えの設計の話です。

次の一歩を一緒に決める作戦会議室へ

API の境界や、外に渡す約束の書き方。
一人で抱えると、内部の都合が勝ちやすい。

作戦会議室では、現場で使える切り方を小さく分け合える場所にしたいです。
窓の枠を一緒に太くしたい方は、のぞいてみてください。

参加する