メインコンテンツまでスキップ

冪等API呼び出し

概要​

PocketSign Link の Service API のいくつかの API では、Idempotency-Key ヘッダを用いた冪等呼び出しに対応しています。

このヘッダーを用いることで、以下のような場面で役立ちます：

  • 同一の通知内容・対象への重複した通知送信を防ぐ
  • ネットワークエラーなどによるAPIのリトライ呼び出しにおいて、重複実行を防ぐ

対応API​

冪等呼び出しに対応しているAPIは、API ドキュメントにおいて、pocketsign.link.v1.idempotency_ttl option がAPI定義に記述されているものです。

冪等キー​

冪等キーは API にリクエストを送信する際に、Idempotency-Key リクエストヘッダーを設定することで指定できます。

サイズ制限​

  • 冪等キーは 255バイト以下 である必要があります
  • 255バイト以上が入力された場合はエラーが返却されます：
{
  "code": "invalid_argument",
  "message": "idempotency key exceeds 255 bytes"
}

有効期限（TTL）​

  • 冪等キーには有効期限があります
  • 有効期限は APIごとに異なります（詳細はAPIリファレンスの pocketsign.link.v1.idempotency_ttl オプションのseconds値を参照してください）
  • 有効期限が切れた冪等キーを再度使用した場合、再び処理が実行されます
  • 原則として冪等キーは再利用されないようなキー設計にしてください

キー設計​

  • UUID やタイムスタンプ、リクエスト ID などを組み合わせた一意性の高いキーの利用を推奨します
  • 冪等キーは同一サービス内の全てのAPIで共有されます。サービス内のすべての API 呼び出しにおいて、冪等キーが一意になるように設計してください

エラーハンドリング​

リクエストボディの不一致​

同じ冪等キーで異なるリクエストボディが送信された場合、処理は実行されずエラーが返却されます：

{
  "code": "failed_precondition",
  "message": "payload differs from earlier request with same idempotency key"
}

有効な冪等キーによるリクエストは、冪等キーに対して常に同一のリクエスト内容で実行する必要があります。 異なるリクエスト内容でリクエストする場合は、異なる冪等キーを使用してください。

同一冪等キーによるリクエストの同時実行​

冪等キーを指定したAPIリクエストの処理が完了しレスポンスが返る前に、同じ冪等キーで同一内容のリクエストを送信した場合、後続のリクエストは、処理は実行されずエラーが返却されます：

{
  "code": "already_exists",
  "message": "identical request is in progress"
}

API実行結果がエラーをレスポンスした場合​

  • API実行によるエラーレスポンスは冪等ではありません
  • 最初の呼び出しがエラーで返ってきた場合、再び呼び出すと異なる結果が返る可能性があります
  • 正常なレスポンス（2xx）の場合にのみ冪等性が保証されます

使用例​

基本的な使用方法​

通知を送信する際に Idempotency-Key ヘッダーを指定します：

curl -X POST https://api.core.mock.p8n.app/pocketsign.link.v1.ServiceService/CreateNotification \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-12345" \
  -d '{
    "target_subscription_ids": ["66af7982-f1ad-4146-b730-21ed790ed799"],
    "title_template": "new message",
    "message_template": "hello"
  }'

レスポンス（キャッシュされた結果）：

{
  "id": "ae74bc0f-bfc9-4d05-83f7-9673803eb6b1"
}

同じ通知 ID が返されるため、ユーザーには新たな通知は送信されません。冪等性により、重複送信が防がれます。

異なるペイロードでの呼び出し（エラーケース）​

同じキーで異なるメッセージ内容のリクエストを送ると、エラーになります：

curl -X POST https://api.core.mock.p8n.app/pocketsign.link.v1.ServiceService/CreateNotification \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-12345" \
  -d '{
    "target_subscription_ids": ["66af7982-f1ad-4146-b730-21ed790ed799"],
    "title_template": "new message",
    "message_template": "different message"
  }'

エラーレスポンス：

{
  "code": "failed_precondition",
  "message": "payload differs from earlier request with same idempotency key"
}

新しいキーでの実行​

新しい冪等キーを使用すると、新しい通知 ID が発行され、ユーザーに通知が送信されます：

curl -X POST https://api.core.mock.p8n.app/pocketsign.link.v1.ServiceService/CreateNotification \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-67890" \
  -d '{
    "target_subscription_ids": ["66af7982-f1ad-4146-b730-21ed790ed799"],
    "title_template": "another message",
    "message_template": "goodbye"
  }'

レスポンス：

{
  "id": "51e6f002-b632-4084-84b2-06a0e5fb2fb6"
}

異なる通知 ID が発行されているため、前回と異なる新しい通知がユーザーに送信されます。

冪等性ヘッダーなしでの呼び出し​

冪等性ヘッダーがない場合は、毎回新しい通知 ID が発行され、ユーザーに通知が送信されます：

curl -X POST https://api.core.mock.p8n.app/pocketsign.link.v1.ServiceService/CreateNotification \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target_subscription_ids": ["66af7982-f1ad-4146-b730-21ed790ed799"],
    "title_template": "new message",
    "message_template": "hello"
  }'

レスポンス：

{
  "id": "fd738cca-c831-46b3-973a-583f689ff301"
}

毎回異なる通知 ID が発行されるため、同じリクエスト内容でも呼び出すたびに新しい通知がユーザーに送信されます。