インターフェース定義書どおりにREST連携を実装する

目標

インターフェース定義書を読んで、そのとおりにRESTクライアントを実装し、送信前の検証・エラーコードのマッピング・タイムアウト処理・連携ログまで備えられるようになります。

なぜ重要なのか

同期RESTの連携で本当に難しいのは、呼び出しではなく、相手が遅い、または様子がおかしいときです。接続タイムアウトを長く設定すると、相手の障害がこちらの障害になり、エラーコードごとの対応を決めないと、誤ったデータを100回再送したり、一時的な障害で業務が止まったりします。そして、送信前の検証をしないと、相手システムのログにこちらのエラーが溜まり、連携担当者間の感情的な消耗が始まります。「悪いデータはこちら側で止める」は、連携開発の基本的なマナーです。

ステップ

/opt/lab/fixtures/eai/spec/IF-ORD-001.mdを読んで、/root/eai/spec.csvを作成してください。1行目はfield,type,length,requiredです。定義書のリクエスト項目を、フィールド名の昇順ですべて書き写します。requiredはY/Nです。
相手システムを起動してください。 python3 /opt/lab/fixtures/eai/rest/partner_api.py 9200(バックグラウンド) http://127.0.0.1:9200/healthのレスポンスを/root/eai/health.jsonに保存してください。statusの値がUPである必要があります。
定義書どおりに、正常な注文1件をPOST /api/v1/ordersで送信し、レスポンスを/root/eai/res-ok.jsonに保存してください。resultCodeが0000である必要があります。
/root/eai/validate.shを作成してください。引数を1つ(JSONファイルのパス)受け取り、定義書を基準に検証して、問題がなければ終了コード0、あれば1行目に理由を出力して0以外の終了コードで終了します。最低でも、必須の欠落 / 長さの超過 / 数値フィールドの文字の3つを検出できる必要があります。
/root/eai/errmap.csvを作成してください。1行目はcode,meaning,actionです。定義書に定義されたレスポンスコードをすべて入れ、actionは、재시도、중단、통보(韓国語の値で、順に再試行、中止、通知を意味します)のいずれかです。
http://127.0.0.1:9200/api/v1/slowは、5秒遅れて応答します。2秒のタイムアウトで呼び出して失敗させ、/root/eai/timeout.txtを作成してください。2行です。
```
exit_code=<curl 종료코드>
policy=<타임아웃 시 처리 방침 한 줄>
```
(山括弧の中の韓国語はプレースホルダーで、順にcurlの終了コード、タイムアウト時の対応方針の1行です。)
/root/eai/send.shを作成してください。引数を1つ(注文番号)受け取り、定義書どおりに呼び出して、レスポンスのresultCodeを1行目に出力します。0000なら終了コード0、それ以外なら0以外の終了コードで終了します。
/root/eai/if.logを作成してください。パイプ(|)で区切られた7つのフィールド、3行以上です。
```
시각|인터페이스ID|송신시스템|수신시스템|응답코드|소요ms|추적ID
```
(コードブロックの韓国語は、順に時刻、インターフェースID、送信システム、受信システム、応答コード、所要ms、追跡IDを意味します。) インターフェースIDはIF-ORD-001で、追跡IDは行ごとに異なる必要があります。

参考

POST: curl -s -X POST -H 'Content-Type: application/json' -d @파일 <URL>(プレースホルダーはファイルです)
タイムアウト: curl --max-time 2 ... / 終了コードは$?で確認します
所要時間: curl -w '%{time_total}'
よくあるミス1: HTTP 200なら成功だと判断することです。業務エラーは、200+resultCodeで来る場合が多いです。
よくあるミス2: 長さの検証を文字数で行うことです。定義書がバイト基準なら、バイトで数える必要があります。
よくあるミス3: 追跡IDを固定値にすることです。呼び出しごとに違って初めて、突き合わせができます。

定義書から項目を抽出する

/opt/lab/fixtures/eai/spec/IF-ORD-001.mdを読んで、/root/eai/spec.csvを作成してください。1行目はfield,type,length,requiredです。定義書のリクエスト項目を、フィールド名の昇順ですべて書き写します。 requiredはY/Nです。

定義書を読んで、必須/任意、型、長さを表に書き写します。この表が、次のステップの検証ロジックの仕様になります。

相手システムの起動と確認

相手システムを起動してください。 python3 /opt/lab/fixtures/eai/rest/partner_api.py 9200(バックグラウンド) http://127.0.0.1:9200/healthのレスポンスを/root/eai/health.jsonに保存してください。 statusの値がUPである必要があります。

連携開発の最初のステップは、常に「相手が生きているか」です。ヘルスチェックのエンドポイントがあれば、まずそれを確認します。

正常な呼び出し

定義書どおりに、正常な注文1件をPOST /api/v1/ordersで送信し、レスポンスを/root/eai/res-ok.jsonに保存してください。 resultCodeが0000である必要があります。

Content-Typeを正確に合わせる必要があります。レスポンスコードのフィールドがHTTPステータスコードとは別であることに注意してください。業務エラーは、HTTP 200で来る場合が多いです。

送信前の検証スクリプト

/root/eai/validate.shを作成してください。引数を1つ(JSONファイルのパス)受け取り、定義書を基準に検証して、問題がなければ終了コード0、あれば1行目に理由を出力して0以外の終了コードで終了します。最低でも、必須の欠落 / 長さの超過 / 数値フィールドの文字の3つを検出できる必要があります。

悪いデータをこちら側で止めることが、連携開発の基本です。必須の欠落、長さの超過、形式の不一致の3つを区別して、理由を出力してください。

エラーコードのマッピング表

/root/eai/errmap.csvを作成してください。1行目はcode,meaning,actionです。定義書に定義されたレスポンスコードをすべて入れ、actionは、재시도、중단、통보(韓国語の値で、順に再試行、中止、通知を意味します)のいずれかです。

各コードに「再試行/中止/通知」のどれかを付けることが核心です。この区別がないと、開発者がすべて再試行するか、すべて諦めます。

タイムアウトの再現

http://127.0.0.1:9200/api/v1/slowは、5秒遅れて応答します。 2秒のタイムアウトで呼び出して失敗させ、/root/eai/timeout.txtを作成してください。2行です。

exit_code=<curl 종료코드>
policy=<타임아웃 시 처리 방침 한 줄>

(山括弧の中の韓国語はプレースホルダーで、順にcurlの終了コード、タイムアウト時の対応方針の1行です。)

curlには、全体の時間を制限するオプションがあります。タイムアウト時にcurlがどんな終了コードを返すかを確認しておけば、スクリプトで分岐できます。

連携クライアントのスクリプト

/root/eai/send.shを作成してください。引数を1つ(注文番号)受け取り、定義書どおりに呼び出して、レスポンスのresultCodeを1行目に出力します。 0000なら終了コード0、それ以外なら0以外の終了コードで終了します。

レスポンスコードに応じて終了コードを変える必要があります。そうして初めて、呼び出した側が判断できます。成功と失敗の両方をテストしてみてください。

連携ログの標準

/root/eai/if.logを作成してください。パイプ(|)で区切られた7つのフィールド、3行以上です。

시각|인터페이스ID|송신시스템|수신시스템|응답코드|소요ms|추적ID

(コードブロックの韓国語は、順に時刻、インターフェースID、送信システム、受信システム、応答コード、所要ms、追跡IDを意味します。) インターフェースIDはIF-ORD-001で、追跡IDは行ごとに異なる必要があります。

追跡IDは、相手システムのログと突き合わせるときに使う唯一の鍵です。呼び出しごとに違う必要があり、リクエストにも一緒に載せて送って初めて意味があります。