API のベスト プラクティス

  • [アーティクル]

生データの取得、広告配信パズルの独自の部分へのフック、またはインフラストラクチャの上に構築することで、当社のプラットフォームを利用することに興奮しています。 ベスト プラクティスに従って、可能な限り最高のエクスペリエンスを得て、API の進化に合わせてアプリケーションを正常に保ちます。 構築を開始するときに、実装コンサルタントと連絡を取り合ってください。

結果をフィルター処理する

フィルター処理を使用すると、返されるオブジェクトのサブセットを指定できます。 たとえば、次の呼び出しでは、アクティブなクリエイティブのみが返されます。

$ curl -b cookies -c cookies 'https://api.adnxs.com/creative?active=true'

int、double、date、または money 型のフィールドの場合は、フィルターに または max_ を追加min_できます。 たとえば、次の要求では、2013 年 1 月 1 日以降に変更されたキャンペーンのみが返されます。

$ curl -b cookies -c cookies 'https://api.adnxs.com/creative?min_last_modified=2013-01-01 00:00:00'

注:

サービスごとに、サービス URL に追加 /meta することで、フィルター可能で並べ替え可能なフィールドを確認できます。 詳細については、「 API セマンティクス」を参照してください。

結果のページ分割

現在、システムに 5 つのクリエイティブしかない場合でも、今後この数が増える可能性があるため、改ページ処理のサポートを利用する方法でアプリケーションを作成する必要があります。 GET 要求のクエリ文字列で と num_elements をstart_element指定することで、結果を改ページできます。 たとえば、次の要求は、応答の最初の 50 個のオブジェクトを返します。

$ curl -b cookies -c cookies 'https://api.adnxs.com/creative?start_element=0&num_elements=50'

次の 50 を取得するには、 を設定 start_element=50するだけです。

注:

改ページに関係なく、返すことができるオブジェクトの最大数は 100 です。 100 個を超えるオブジェクトを要求した場合、最初の 100 個のみが返され、エラー メッセージは表示されないことに注意してください。 詳細については、「 API セマンティクス 」ページを参照してください。

通話を調整する

1 分あたりの API に対して行うことができる要求の数には制限があります。 これらの制限は、読み取りと書き込みのレート制限に分類されます。 現在、既定の読み取りおよび書き込み制限は 1 分あたり 1000 です。 これらのカウンターは分の終わりにリセットされますが、調整制限を超えると、 API は HTTP 429 (要求が多すぎる) 応答コードで応答します。 ヘッダーのフィールドで指定した秒数で要求を Retry-After 再試行します。

同時要求の上限は一度に 20 個もあります。 この制限を超える場合、 HTTP 200 が返されますが、 エラー ペイロードが返されます。

メンバーのレート制限を超えた要求に応答するヘッダー値の例を次に示します。

HTTP/1.1 429 Too Many Requests
Content-Type: application/json; charset=utf-8
Retry-After: 16
X-AN-RequestId: 98472eb263664a7b
X-Count-Read: user:101,member:101,serviceHostUser:75,serviceHostMember:75,hostUser:101,hostMember:101,ip:0
X-Count-Write: user:0,member:0,serviceHostUser:0,serviceHostMember:0,hostUser:0,hostMember:0,ip:0
X-Ratelimit-Read: 100
X-Ratelimit-System: 100-Default
X-Ratelimit-Write: 60
Content-Length: 358

既定値に依存するのではなく、フィールド値を渡す

既定値に依存するのではなく、必要なフィールド値を渡すことがベスト プラクティスです。 既定値が変更され、既定値に依存している場合は、予期しない結果が発生する可能性があります。

不要な更新を避ける

オブジェクトを更新するときは、変更されていないフィールドを渡さないでください。 これを回避する良い方法は、GET 呼び出しをキャッシュし、キャッシュを行う変更と比較し、その後、異なる場合にのみ PUT 呼び出しを行う方法です。

不要な認証を避ける

5 分間に 10 回正常に認証できます。 この 5 分以内にそれ以降の認証が試行されると、エラーが発生します。

注:

認証すると、2 時間アクティブな状態の承認トークンを受け取ります。 呼び出し応答でerror_idを受信した "NOAUTH" 後にのみ、再認証することをお勧めします。 この方法に従う場合、上記の制限は実装に影響を与えるべきではありません。

認証手順については、「 認証サービス」を参照してください。

構成駆動型 API エンドポイントを使用する

API ベース URL を簡単に変更できることを確認します。 次の例では、API URL は変数として定義されており、コード ベース全体で使用できます。 その URL を変更する必要がある場合は、1 つの場所で変更できます。

$config = "https://api..com";

API ラッパーを構築する

要求を送信し、応答を処理するコードを一元化することをお勧めします。 これにより、ログ記録、エラー処理などを 1 つの場所で実行できます。

すべてのレポートを同時にプルしない

これにより、レポート バックエンドが過負荷になり、レポートが遅延し、1 日の後半に実行されるレポートにも影響を与える可能性があります。

API を使用する前に API Wiki 全体を読み取る

API Wiki には、統合の開発に役立つ多くのヒント、コツ、例があります。

統合コードを使用する

Xandr ID を格納するのではなく、統合コードを使用して API 内のオブジェクトを参照できます。 これらのコードは、オブジェクト型と Xandr メンバー間で一意である必要があります。 次の例では、統合コードを使用してキャンペーンを識別します。

"creative":{
                "id":6,
                "active":true,
                "member_id": 5,
                "code": your_internal_code
}

API 呼び出しが成功したと想定しないでください

成功した API 呼び出しはすべて、 を含む応答を"status""OK"受け取ります。 応答にこの状態が含まれていない場合、何らかの理由で呼び出しが失敗しました。 "status"が "error"の場合、エラー メッセージが応答に含まれます。 成功した応答の例を次に示します。

{
   "response": {
      "status": "OK",
      "campaign": {
         ...
      }
   }
}

応答の追加フィールドを許可する

API チームが新しい機能を実装する場合は、さまざまな API サービスに新しいフィールドを含める必要があります。 統合は、以前に返されなかった各サービスの追加フィールドを処理するのに十分な柔軟性を備えている必要があります。

破壊的変更に注意する

新しい機能を追加すると、サービスは絶えず変化しますが、クライアントが API を基に構築するアプリケーションも適切に適応できるように、安定性を生み出すために最善を尽くします。

破壊的変更を導入する場合、運用環境の API の 2 つのバージョンをサポートします。1 つは破壊的変更あり、もう 1 つは破壊的変更なしで 60 日間サポートされます。 これらの変更は、API リリース ノートで発表します。 破壊的変更を構成する内容の詳細については、「破壊的変更」ポリシー を 参照してください。

オブジェクトの制限に注意してください

Xandr は、各メンバーがプラットフォーム上で作成および使用できるオブジェクトの数を制限します。 この制限には、非アクティブなオブジェクトと未使用のオブジェクト (非アクティブ状態に設定されたキャンペーン、インプレッションを配信したことがないプレースメントなど) が含まれます。 オブジェクト制限サービスを使用して制限を表示し、使用状況を事前に監視する必要があります。