API

サイトには、ページを表示する代わりにリクエストに応答する部分もあります。メッセージを保存するお問い合わせフォーム、Stripe に決済を依頼する購入手続き、翌日のリマインダーを送信するジョブなどです。これらはそれぞれサイトのコード内のルートです。API ビューでは、エディターを離れずに各ルートを試せます。

開き方

サイトにルートがあると、ページパネルの上部に ページ | API の切り替えが表示されます。API をクリックすると、ルートが表示されます。

一覧はページと同じ構成で、アドレスの各部分が1つの階層になります。

• 1つのメソッドに応答するルートでは、health の横に GET があるように、同じ行にメソッドが表示されます。行をクリックすると開きます。
• 複数のメソッドに応答するルートを開くと、GET、POST、DELETE など、メソッドごとに行が表示されます。
• アドレスの先頭部分が共通するルートは、フォルダーにまとめられます。
• サイトマップ、robots.txt、アプリのマニフェスト、ソーシャル共有用画像も、コードで生成されるため一覧に表示されます。

ルートが多いサイトでは、上部に エンドポイントを絞り込む フィールドが表示されます。

エディター上部のアドレスバーに /api/ で始まるアドレスを入力するか、その下に開く一覧からルートを選ぶこともできます。/api/tools/figma のような完全なアドレスを入力すると、ルートが開き、figma が自動入力されます。

スマートフォンでは、上部のサイトメニューを開いて API を選ぶか、ページ一覧からルートを選びます。

リクエストの送信

メソッドを選ぶと、キャンバスが API ビューに切り替わります。上部のアドレスには送信先が正確に表示され、入力に合わせて更新されます。

• プレビュー は作成中の下書きに送信します。公開中 は公開済みのサイトに送信します。
• 送信 でリクエストを送信します。⌘↵ / Ctrl+Enter も使えます。

パラメーター

ルートがアドレスから読み取る値です。パス の値は [id] のような角括弧で囲まれた部分で、必須 と表示されます。クエリ の値は ? の後にある、ルートが読み取る値です。一覧にない値を送信するには、パラメーターを追加 をクリックします。

ボディ

POST、PUT、PATCH、DELETE で使用します。ルートが読み取るフィールドはあらかじめ表示されるので、フォームと同じように入力できます。ボディを自分で書くには、JSON に切り替えます。フォームを読み取るルートにはフォームフィールドが表示され、ブラウザーがフォームを送信するときと同じ形式で送信されます。

ヘッダー

サインイントークンなど、リクエストと一緒に送信する追加情報です。追加するには ヘッダーを追加 をクリックします。

レスポンスの確認

最初にステータスと、応答にかかった時間、レスポンスのサイズが表示されます。その下には次の内容が表示されます。

• ボディ には、返された内容が読みやすい形式で表示されます。JSON は色分けされ、XML と HTML は整形されます。HTML には ページ ビューもあります。CSV は表、画像は画像として表示されます。
• ヘッダー には、ルートが返したヘッダーが表示されます。
• コンソール には、応答中にサイトのサーバーが出力した内容が表示されます。プレビューに送信したリクエストで利用できます。

CSV エクスポートや生成画像など、ファイルを返すルートには ダウンロード ボタンが表示されます。訪問者を別の場所へ転送するルートでは、転送先が表示されます。転送先がサイト内のページなら、ページを開く が表示されます。

時計をクリックすると、このセッションで送信したリクエストを確認し、再び開くことができます。

問題が起きたとき

応答中にコードでエラーが発生すると、API ビューにエラーと発生したコードの行が表示されます。

• コードを開く は、該当するファイルをコードエディターで開きます。
• AI で修正 は、エラーとサーバーの出力内容を含むチャットを開始し、AI が修正できるようにします。

サインインした状態でのリクエスト

サインインしたユーザーにのみ応答するルートもあります。まず、サイトで使うメールアドレスとパスワードを指定して、サイトのサインイン用ルートにリクエストを送信します。API ビューはサイトが設定した Cookie を保持し、ブラウザーと同じように、次のリクエストと一緒に送信します。Cookie は ヘッダー の Cookie に表示されます。クリア でサインアウトできます。

ルートでトークンを使う場合は、Authorization ヘッダーを自分で追加することもできます。

定期実行ジョブと決済

これらのテストでは、シークレットをコピーする必要はありません。

• スケジュールに従って実行されるルートは、サイトが保持するシークレットを確認します。API ビューが自動で送信します。
• Stripe の Webhook は署名を確認します。API ビューでは、最初からボディに Stripe のテストイベントが入り、サイト固有のシークレットで署名されます。署名付きテストイベントの送信先は プレビュー のみなので、公開中のサイトの実際の注文にテストが影響することはありません。

ルートの追加

API を表示しているときは、ページパネル上部の + をクリックします。ページ を表示しているときは、メニューから 新しいエンドポイント を選びます。

• パス は、ルートのアドレスのうち /api/ より後の部分です。tools/[id]/reviews のように、変わる部分には [id] を使います。
• メソッド は、ルートが応答する方法です。必要な数だけ選べます。
• 説明 を使うと、新しいチャットで AI にルートを作成してもらえます。空のファイル では、自分で書くための空のファイルから始めます。

新しいルートは作成されるとすぐに API ビューで開くので、その場で試せます。

知っておくと便利なこと

• リクエストの制限時間は12秒です。それを過ぎてもルートが送信を続けている場合は、その時点までに届いた内容が表示されます。
• API ビューでは最大 512 KB のレスポンスを表示でき、最大 5 MB のファイルをダウンロードできます。
• 同時に実行できるリクエストは3件、送信できるリクエストは1分あたり最大30件です。
• リクエスト、履歴、Cookie は、エディターを再読み込みするまで保持されます。
• 公開中 に送信するには、サイトを公開する必要があります。