ReplitでAPIを作るときの進め方

ReplitでAPIを作るときは、Agentへ「APIを作って」と頼む前に、path、method、認証、入力、成功応答、失敗応答を決めます。この契約が先にあると、画面とサーバーの期待が揃い、テストで何を確認すればよいかも明確になります。APIの機能を増やすより、最初の1 endpointが不正入力や権限不足を安全に扱うところまで作るのが先です。

この記事の読者が持ち帰るものは、Agentに渡せる最小API仕様と、その場で確認できるテスト表です。ReplitはAgentを使ってアプリやサーバー側処理の作成を支援しますが、認証設計、データ権限、外部サービス契約を自動で決めてよいわけではありません。必要な判断は依頼前に人が確定します。

Endpointの前にResourceと利用者を決める

「ユーザーを管理するAPI」では、誰が何をできるかが見えません。たとえばTask APIなら、ログイン中の利用者が自分のTask一覧を取得し、Taskを1件作成・更新・削除する、という単位に分けます。外部サービスへ公開するAPIか、同じアプリの画面から呼ぶ内部APIかも最初に決めます。公開範囲で必要な認証、rate limit、監視が変わります。

API契約は次の表から始められます。

表は横にスクロールできます

項目	例	未決のまま実装した場合
Method / path	POST /api/tasks	読取と更新の責任が曖昧
認証	サインイン済み利用者	誰でも作成できる
Request	title（1〜120文字）	長さや空欄の扱いが不一致
Success	201と作成済みTask	画面が受け取る形式が曖昧
Error	400、401、403等	失敗理由を画面で扱えない
権限	自分が所有するTaskだけ	他人のデータへアクセスできる

status codeは例です。アプリの既存契約、フレームワーク、利用者との約束に合わせ、既存APIがある場合はそれに揃えます。新しい形式を作ること自体が目的ではありません。

Agentへ渡す依頼を具体化する

contractが決まったら、次のように依頼できます。

POST /api/tasksを実装してください。認証済み利用者だけが使え、titleは1〜120文字の文字列です。利用者IDはrequest bodyから信用せず、認証済みsessionから取得してください。保存後は作成したTaskを返し、入力エラー、未認証、権限エラーを区別します。既存のresponse形式とテスト構成を調べ、変更前に対象ファイルとテスト案を提示してください。既存DBのデータ削除や本番反映は行わないでください。

Agentが返す計画で、データの所有者、エラー、既存仕様との互換性を確認します。具体的なフレームワーク名やファイルパスは、実際のプロジェクト構成を確かめてから含めます。推測したファイル名をそのまま命令すると、似た名前の別routeに実装されることがあります。

Request validationと応答の境界

Request bodyは、クライアントが送ったから正しいとは限りません。必須項目の有無、型、長さ、許可値をサーバー側で検証します。SQLやcommandへ使う値は、文字列連結でそのまま埋め込まず、ORMやparameterized queryなど既存の安全な方法を使います。

応答には、画面が次に何をするか決めるための情報だけを含めます。DB内部の接続情報、stack trace、外部API key、他ユーザーの情報は返しません。エラー本文は利用者向けに安全な説明とし、詳しい診断はアクセス制限したserver logへ記録します。request body全体をログへ出すと個人情報や認証tokenが残ることがあるため、記録項目を絞ってください。

認証と認可を分ける

Authenticationは「誰が呼び出したか」を確認すること、authorizationは「その人がこの操作をしてよいか」を確認することです。ログイン済みだからすべてのresourceを読めるわけではありません。各endpointで、操作対象の所有者やroleを確かめます。画面上でボタンを隠すだけでは、直接APIを呼ぶ利用者を止められません。

表は横にスクロールできます

状況	期待する扱い
認証情報なし	認証を要求し、個人データを返さない
自分のresource	契約した操作だけ許可
他人のresource	既存仕様どおり拒否し、情報を漏らさない
role不足	管理操作を拒否
期限切れsession	再認証を求める

403と404の使い分けは、対象の存在を漏らすリスクや既存UIの意味に応じて決めます。すべてのAPIで同じstatus codeに機械的統一するのではなく、情報開示と画面の扱いを合わせます。

まずは使ってみる

記事の文脈に合うToolへ進めます。報酬の有無で見た目は変えていません。

• 

  Replit

  公式サイトを見るTool詳細を見る

Error contractで修正可能な失敗を返す

エラーをまとめて500へ変換すると、利用者が直せる入力ミスとサーバー障害が区別できません。一方でDBエラーの詳細をそのまま返すと、内部情報を漏らす恐れがあります。画面に返す分類と、サーバー側だけに残す診断情報を分けます。

表は横にスクロールできます

ケース	API側で行うこと	利用者に返すもの
必須項目不足	保存前にvalidation	どの入力を直すか分かる説明
未認証	処理を止める	サインインが必要という案内
権限なし	対象処理を実行しない	許可されていないこと
見つからない	既存contractに従う	再試行または戻る選択
DB / 外部service障害	詳細を秘匿して記録	再試行可能か、問い合わせが必要か

Agentへ「エラーを適切に処理」とだけ頼まず、利用者へ見せてよい情報とログへ記録しない情報を指示します。秘密情報、session token、個人情報をログ対象から除外し、安全に追跡できる識別子が既存構成にあれば利用します。

小さなテストで副作用まで確認

まず読み取り可能なhealth checkや固定応答でrouteが動くことを確かめ、その後DB接続と認証を加えると原因を切り分けやすくなります。各段階で成功を確認し、複数の変更を一度に入れないようにします。永続データが不要ならDBを加える必要はありません。

Task作成APIなら、次の入力で確認します。

表は横にスクロールできます

Test input	期待する結果
title=「見積もりを送る」（認証済み）	1件だけ作成され、利用者へ返る
titleが空欄	保存されず、入力エラーが返る
titleが上限を超える	仕様どおり拒否される
認証情報なし	作成されず、認証エラー
他利用者のTask IDを更新	変更されず、権限エラー
同じrequestを再送	二重作成の扱いが契約どおり

実際のstatus codeやJSON shapeはプロジェクトで定義します。HTTP statusだけでなく、DBへの副作用が起きなかったことも確認してください。エラー応答のあとに中途半端な行が作られるなら失敗です。二重送信を防ぐなら、画面のボタン無効化だけでなくserver側のidempotencyや重複制約が必要か検討します。

Replit上のSecretと公開先

外部API keyやDB credentialをsource code、frontend、公開Gitへ書きません。Replit Secrets機能などで環境変数として渡し、server側で読み込みます。ブラウザーのJavaScriptに埋め込んだ値は利用者に見えるため、Secretsへ保存しただけでは秘密になりません。

Previewと公開環境では環境変数やDB接続先が異なる場合があります。公開前に必要なkeyが公開側にも設定されているか、ただし値を画面やlogへ出していないかを確かめます。外部APIの認証方法、利用条件、課金、quotaはそのサービスの一次情報も確認します。Replit内の設定が外部API利用契約を代替するものではありません。

APIを公開する前の確認

公開URLから、正常入力、未認証、権限不足、不正入力、依存service停止を確認します。CORSを広げれば解決するとは限りません。呼び出し元を限定できるか、cookieやtokenの扱いは既存の認証方式に合うかを確認します。公開APIならrate limitingや濫用時の対応も必要です。機密データを扱う場合は、安全な通信だけでなくアクセス制御、log、保持期間まで点検します。

Previewだけで通ったテストと公開環境でのテストを分けます。DBや外部serviceの設定差を確認し、同じテストデータを本番へ送らないでください。データ変更を含む試験はテスト環境で行い、利用者データへ副作用を出さない手順を選びます。

AIものさしの判断

ReplitでAPIを作る際は、Agentの生成能力より先に契約を固めるのが安全です。最低でも利用者、resource、request、response、error、権限を決めれば、実装とテストに境界を作れます。APIが動くことは、認可や秘匿が正しいことと同じではありません。

画面内だけで使う小さなAPIなら、既存の認証とresponse形式に沿って最小routeから始めます。外部公開、個人情報、決済、削除処理を含む場合は、権限・監視・復旧を確認できるまで公開を保留してください。未決のcontractが残るなら、Agentに推測で補完させず質問を返させます。