3Min API

基本概念

クイックスタートで紹介した用語をさらに詳しく見ていきます。

1. API

プログラム間でデータをやり取りするための通信プロトコルです。

3Min APIでは：

  • バックエンドコードなしでAPIを作成
  • 標準的なJSONデータを受信
  • データは自動的に保存され、Webhookで転送可能

2. エンドポイント

データを受信するAPIアドレスです。1つのAPI = 1つのエンドポイント。

各エンドポイントに含まれるもの：

  • 固有のURLパス（自動生成）
  • 必須フィールド（任意）
  • サンドボックス/本番環境の分離
  • 環境別APIキー (tm_test_xxx..., tm_live_xxx...)

3. JSON

3Min APIは標準的なJSONデータを受け付けます。

対応フィールドタイプ：

StringテキストExample
stringテキスト"hello"
number数値123, 45.67
boolean真/偽true, false
arrayリスト[1, 2, 3]
objectネストされたデータ{"key": "value"}

例（注文情報）：

{
  "order_id": "ORD-2024-001",
  "amount": 45000,
  "items": ["Item A", "Item B"],
  "paid": true,
  "customer": {
    "name": "John Doe",
    "phone": "010-1234-5678"
  }
}

4. 必須フィールド（任意設定）

必須フィールドを定義しなくても、標準的なJSONは受け付けられます。

JSONデータに必ず含めるべきフィールドを指定できます。

必須フィールドを設定すると：

  • 必須フィールドが不足しているリクエストは拒否されます（400エラー）
  • データ品質を確保できます

5. サンドボックス vs 本番

環境APIキー用途
サンドボックスtm_test_xxx...開発・テスト用
本番tm_live_xxx...ライブサービス
  • 環境はAPIキーのプレフィックスで判別されます
  • Webhookは環境ごとに個別設定が可能です
  • 本番にデプロイする前にサンドボックスで十分にテストしてください

6. APIキー

エンドポイント呼び出し時の認証に使用します。オーナーのデフォルトAPIキーはエンドポイント作成時に自動生成され、削除できません。キーが漏洩した場合は再生成できます。

APIキー環境用途
tm_test_xxx...サンドボックステスト用、本番に影響なし
tm_live_xxx...本番ライブサービス用、実データを処理

APIキーが漏洩した場合は直ちに再生成してください。

コラボレーションキー

コラボレーションキーを作成し、協力者を招待して、コラボレーションキーごとにログと統計を個別に管理できます。

コラボレーションキーでログをフィルタリングして、コラボレーションキーごとの利用状況を追跡できます。

コラボレーションキーごとに許可する操作（POST/GET/PUT/DELETE）を環境別に個別設定できます。読取（GET）権限は単件・一覧・検索のいずれにも適用されます。

7. Webhook

データが到着した際に、指定したURLに自動通知を送信します。

2種類のWebhook：

Webhook設定場所説明
オーナーWebhookダッシュボード → API → エンドポイント詳細すべてのAPI呼び出し通知を受信
協力者WebhookAPI呼び出し時のリクエストヘッダー協力者が処理結果を直接受信

リトライポリシー：15秒以内に2xxを返却。失敗時はキューから時間単位でリトライ

注意：すべてのWebhookリトライが失敗しても、データは安全に保存されています。ログでWebhookのステータスを確認してください。

8. ポーリング

データを受け取るもう一つの方法です。こちらから皆さんのURLへ送る代わりに、皆さんのクライアントがポーリングエンドポイントを定期的に呼び出し、前回以降に届いた分だけを受け取ります。

Webhookとポーリングの比較：

項目Webhook（プッシュ）ポーリング（プル）
呼び出す側3Min APIが皆さんを呼び出します皆さんのクライアントが当社を呼び出します
必要なもの15秒以内に応答する公開URL着信は不要。外向きのHTTPSだけで動きます
遅延レコード保存後、数秒ポーリング間隔に約60秒の安定待ちが加わります
コスト無料 — 配信はAPI呼び出しに数えられませんポーリング1回につきAPI呼び出し1回。空の応答も含みます

受け側に公開URLがあり、データが届いた瞬間に反応させたいならWebhookです。既定の選択肢です。

公開URLがない場合 — ローカル開発、社内ネットワーク、ファイアウォールの内側、常時稼働のサーバーがない — あるいは受け側が自分のペースを制御したい場合はポーリングです。

両者は排他的ではありません。同じエンドポイントで両方を有効にできます。リアルタイム反応はWebhookで、取りこぼしは夜間のポーリングで補う、といった使い方です。

リクエスト例：

# First call - since a point in time
GET /api/v1/data/my-endpoint/poll?since=2026-09-01
Authorization: Bearer tm_test_xxx

# Response - oldest first
{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "limit": 100,
    "poll_cursor": "eyJ0IjoiMjAyNi0wOS0wMVQwMDowMDowMFoifQ"
  }
}

# Next call - send the cursor back
GET /api/v1/data/my-endpoint/poll?cursor=eyJ0IjoiMjAyNi0wOS0wMVQwMDowMDowMFoifQ

カーソルの仕組み：

  • 最初の呼び出しにはsince（RFC 3339またはYYYY-MM-DD、常にUTCとして解釈）を渡すか、何も渡しません。何も渡さなければその時点から購読します。sinceとcursorを同時に送ることはできません。
  • next_cursorはバックログが残っている合図です — すぐにもう一度呼び出してください
  • poll_cursorは追いついた合図です — 保存して次の周期まで待ってください
  • レコードは古い順、1ページ最大100件（limit、1〜100）。応答には2つのカーソルのうち必ず1つだけが含まれます

直近60秒ほどはキューが追いつくまで保留されます。スキップではなく、後のポーリングに繰り延べられるだけです。再試行や再起動で同じレコードが再配信されることがあるため、レコードidを基準に冪等に処理してください。

9. データ保持

レコードの保持期間には上限があります。データが3Min APIの外へ出る経路は、ダッシュボードではなくWebhookまたはポーリングエンドポイントだと考えてください。

環境別ポリシー：

環境ポリシー備考
本番（有料プラン）最低60日保持保持期間を過ぎると月単位でまとめて削除されます
サンドボックス（有料プラン）30日後に自動削除テスト用であり保管場所ではありません
無料プランエンドポイント作成から7日後に全削除エンドポイント単位で削除

データの取り出し方：

  • Webhook：レコードが届いたその都度、指定URLへ送信されます
  • ポーリング：前回の呼び出し以降に届いた分を自分で取りに行きます — 上の8番を参照
  • ログ：保持期間内はダッシュボードで個別レコードを参照・検索できます
  • 利用統計は別に保持され、レコードが削除されても残ります。ダッシュボードのグラフはそのままです