リリースの契約から始めましょう
導入環境の API ドキュメントを取得し、サービスアドレス、認証方法、リクエストとレスポンスの構造、および利用可能な機能を確認してください。OpenAPI は、HTTP API 操作、パラメーター、およびデータモデルを記述するための標準です。実際の統合には、製品に付属の契約書を使用してください。
この準備ガイドでは、未検証の AI-Soda Brain エンドポイント、認証フィールド、および SDK パッケージ名を省略しています。コードを記述する前に、クライアントチームとサービスチームに同じ契約とその対象となるリリースについて合意してもらいます。
APIの基本仕様を確認するチェックリスト
| 契約品目 | 解決すべき質問 |
|---|---|
| ID と権限 | 操作はユーザーとして実行されますか?それともアプリケーションとして実行されますか?その範囲はどのように制限されていますか? |
| リクエスト | フィールドタイプ、必須フィールド、サイズ制限、エンコード制約 |
| 応答 | 結果、ソース、ステータス、完了はどのように表現されますか? |
| タイミングとキャンセル | タイムアウト、キャンセル、長時間実行タスクの状態はどのように処理されますか? |
| 失敗 | 再試行できるエラーはどれですか?異なる入力または権限が必要なのはどれですか? |
| バージョン | 互換性ポリシー、変更通知、非推奨スケジュール |
小規模なエンドツーエンドテストを 1 つ完了する
- 隔離されたテスト環境で最小特権の ID を構成します。フロントエンドコードやサンプルリポジトリに認証情報を含めないようにしてください。
- 合成質問による呼び出しを 1 回成功させ、編集されたリクエストと応答を保持します。
- 無効な入力、不十分な権限、タイムアウト、キャンセルをカバーします。クライアントが空の結果ではなく、明確な障害状態を表示することを確認します。
- ビジネスインターフェイスを接続する前に、欠落しているフィールドや不明なフィールドの動作をコントラクトに対してテストします。
操作の影響に応じて再試行を設計する
通信が切れても、サーバー側で処理が実行されたかどうかは分かりません。状態を変更しうる操作では、再試行の前に冪等性と処理状況の確認方法を調べます。読み取り専用のクエリでは、再試行回数の上限、間隔の延ばし方、中断条件を定めます。
受諾時に、契約バージョン、クライアントバージョン、テストケース、既知の制限を記録します。後続のアップグレードでは、トラフィックを徐々に増やす前に、同じケースを検証してください。
さらに読む
このガイドは役に立ちましたか?
