easyPoints

# Async API

# Async API（非同期型API）とは

APIリクエストは同期型（synchronously）または非同期型（asyncronously）に区分されます。同期型のリクエストは即座に実行されるのに対し、非同期型のリクエストはバックグラウンドで処理されます。

同期型のリクエストは loyalty.slrs.io ドメインを使用し、非同期型のリクエスト async-api.easypoints.app パスを使用して行われます。

# Async APIのメリット

Async APIは、easyPoints APIで発生する全てのサーバー側の5xx エラー及び429スロットリングエラーに対し、リトライを行います。

これによりサーバーからの成功のレスポンスを待つことなく、プラグラムの実行が可能となります。

# Async APIの使用が推奨される状況

以下のような場合はAsync APIの利用が推奨されます。

  • サーバー側のリクエストエラーの処理を行いたくない場合
  • スロットリングによるエラーの処理を行いたくない場合

# Async APIの使用が推奨されない状況

以下のような場合はAsync APIの利用が不適切な可能性があります。

  • リクエストの成功/失敗の情報が重要な場合
    Async APIではリクエストの処理自体が成功したかどうかを判別することはできません。
  • リクエストの処理がすぐ行われるべき場合
    Async APIはバックグラウンドで処理されるため、最長で24時間程度かかる場合がございます。
  • リダイレクトリクエストを処理したい場合
    Async APIのエンドポイントへのリクエストは308リダイレクト（恒久的リダイレクト）を使用するため、リダイレクトされたリクエストは処理されません。

WARNING

Async APIはリクエストが送信された時に認証情報、ルート、ボディの値等が正しくない場合も成功のレスポンスが返されます。リクエスト送信の成功レスポンスでは、リクエスト内容の有効性は確認できませんので、Aysnc APIの利用時はリクエスト内容に誤りがないことを念入りにご確認ください。

# Async APIが失敗する場合

Async APIには独立したサーバーを設けていますが、サーバー側やクライアント側のエラーにより処理が失敗する可能性はございます。また、Async APIのホストサーバー自体が不具合・障害の影響によりアクセスができなくなる可能性もございます。

また、リクエストの認証情報、ルート、ボディの値等が正しくない場合、同期型のAPIリクエストと同じように失敗します。リクエストの情報が正しいことを確認するためには、同期型APIのパスを用いて検証してください。

# Async APIで使用可能なパス

現在Aync APIに対応している処理はポイント付与のみになります。

# Async APIを呼び出す方法

基本的な呼び出し方は同期型と同様ですが、使用するパスが異なります。

POSTリクエストに対してAsync APIを呼び出す場合、以下のようなベースパスをご利用ください。

ドメイン:

async-api.easypoints.app

リクエストとレスポンスの例:

ポイントの付与にAsync APIが使用され、正常に送信された場合以下のようなレスポンスが発生します。

POST "https://async-api.easypoints.app/api/shopify/point_allotments"
Body {
  "point_value": 200,
  "customer_id": "123"
}

{
    "status": 202
}

こちらの成功レスポンスは、正常にリクエストが送信されたことを意味しますが、前述の通り、リクエスト内容の実行の成功を表すものではありませんのでご注意ください。

← Webhook →