要約

  • 現行のOpenAPIでは、RDNS、ルート、ASPAのバッチ要求は create、update、delete に分かれる一方、結果項目が宣言するプロパティーは status と message の二つだけである。
  • 必要なのは内部ログの公開ではない。要求配列と添字、またはクライアントが付けた不透明なキーを結果へ返し、操作種別と機械判読可能な結果を結ぶ小さな対応表である。

静かな日に起きる問題ほど、仕様の輪郭をよく示すことがある。ある運用者が、二つのルートオブジェクトを作成し、一つを更新し、もう一つを削除するバッチを送る。APNICは入力を検証し、非同期タスクのURLを返す。しばらくしてタスクを読むと、複数の結果が並んでいる。

公開されているOpenAPIは、結果の状態を三つに限定する。success、failure、notification である。各項目には message も置ける。だが、その項目が create[0] への答えなのか、update[0] なのか、delete[0] なのかを示すフィールドはない。クライアント側の識別子を返す欄も、対象リソースのIDや location もない。応答順が要求順に対応するという規範的な記述も見当たらない。

これは稼働中のサービスに障害があるという主張ではない。確認したのはAPI版 0.0.2、OpenAPI 3.0.0 の文書で、59,622バイト、1,934行だった。認証が必要な書き込みは一度も試していない。結果が並べ替えられた、別の操作に誤対応した、欠落した、あるいは会員が誤って再送したという事実は確認されていない。

実装は常に安定した順序を守っているかもしれない。メッセージに対象が明記され、内部の監査記録には完全な対応関係が残っている可能性も高い。ここで確認できる境界は一つだけだ。その保証を、調べた公開の機械契約からは取り出せない。

APNIC側の最も強い説明

現行設計には評価すべき要素がある。POST、PUT、DELETEはすべて非同期タスクとして扱われる。スキーマ検証を通った要求にはタスクリンクが返り、クライアントは処理状況をポーリングできる。タスクは元の要求を保持し、完了後には処理時刻、HTTPステータス、応答内容を持てる。

バッチ全体を単純な真偽値で済ませてもいない。APNICは batch-response に各アクションの結果を分けて入れ、必要に応じて通知も含めると説明する。冒頭には、可能な範囲でバッチをトランザクションとして反映し、一般にはWhoisへ影響する操作を除いてトランザクション処理するとある。

読み取りAPIやMyAPNICで結果を照合する道もある。APNICは正式提供前にテスト環境を用意し、APNIC 57でハッカソンを行い、APNIC 58で製品デモを開いた。仕様書には非公開と公開の二つのフィードバック先も記されている。

したがって、簡潔なスキーマは意図的なのかもしれない。実装上の順序規則は十分に安定し、メッセージだけで人間が対象を特定できるのかもしれない。トランザクション境界が結果の分岐を減らし、公開不要な内部テストが対応関係を保証している可能性もある。

この反論を先に認めなければ、文書にないものを障害へ膨らませることになる。本稿は、APNICが要求を失う、重複させる、並べ替える、誤った対象へ適用すると述べていない。被害を受けた会員がいるとも述べない。資格情報、非公開オブジェクト、データベース構成、トランザクションログの公開も求めない。

問いは狭い。自動化の利用者が、権威ある契約だけを根拠として「この返答は、あの要求項目へのものだ」と判断できるかどうかである。

入力には番地があり、出力にはない

要求側の設計は細かい。RDNS、ルート、ASPAはいずれも、操作を create、update、delete の配列に分ける。リソースと操作によって項目の形も変わる。ルート削除は既存IDを指せる。RDNS削除は範囲を指定する。ASPA更新はID、カスタマーASN、プロバイダーASN群を持ち得る。

つまり、各要求項目には元から番地がある。リソース種別、操作、配列内の位置である。内容を公開しなくても、クライアントは自分が delete[1] を送ったことを知っている。

共通の応答へ移ると、その番地が消える。results の要素に宣言されたプロパティーは、正確には status と message だけだ。前者は結果を大まかに分類し、後者は構造化規則のない文字列である。「これは delete[1] の結果だ」と示す機械フィールドがない。

リストの順序で十分という考え方は成り立つ。ただし、順序が仕様化されていれば、である。作成、更新、削除の順に連結するのか。通知も一項目として数えるのか。検証段階で除かれた操作にも結果が付くのか。トランザクション全体の失敗は、各項目の失敗として並ぶのか。確認した文書は答えを定めていない。

OpenAPIの規則は、もう一つの差を生む。オブジェクトにプロパティーが列挙されていても、それだけでは必須にならない。必須にするには required 配列へ名前を入れる。現行の batch-response にはトップレベルの required がない。したがって type と results は許される形として記述されるが、最低限返る形として契約されてはいない。task、task-link、success-response のトップレベルも同様である。

実際のサーバーがそれらを省略するという意味ではない。仕様から生成したクライアントや契約テストが、仕様だけを根拠に必須扱いできないという意味だ。

暗黙の順序は、やがて固定資産になる

APNICの実例ではない、試験用の想定を置く。三つの作成と二つの削除に対して、success、failure、success、success、notification が返る。規則がなければ、クライアントは自分で対応表を作る。要求配列を決め打ちの順で連結する、メッセージから対象名を抜く、通知を数から除外する、または対象群をすべて再取得する。

どの方法も当面は動く。だが、新しい通知が一つ入れば添字がずれる。表現が変わればメッセージ解析が壊れる。バッチを一件ずつに分ければ曖昧さは減るが、効率とトランザクションの利点を捨てる。全件照合は安全でも、遅延、API呼び出し、レート制限の負担を増やす。

この負担は均等ではない。大規模なネットワークは専用アダプターと回帰試験を持てる。小規模な会員はサンプルコードを採用し、隠れた前提を何年も抱える。結果として、オープンソースの保守者やベンダーが、公式文書にない意味の管理者になる。

明示的な対応欄は、局所的な不確実性を局所的なままに保つ。一項目の失敗が分かれば、その対象だけを確認できる。分からなければ、バッチ全体の再送や広い読み戻しへ処置が膨らむ。

必要なのは薄い結果マップ

最小案は、結果に要求配列名とゼロ起点の添字を付けることだ。create:0、update:2、delete:1 のようにすればよい。より変更に強い案は、クライアントが各項目へ不透明なキーを付け、サーバーがそのまま返す方式である。キーはプレフィックスやASNを含む必要がなく、送信者のジョブ内部だけで意味を持てばよい。

同じ行に操作種別と安定した機械コードを置ける。安全で適切なら、対象IDや location を返す。失敗理由は構造化した問題オブジェクトで表し、自由文を主キーにしない。次の行動も、修正、ポーリング、照合、再送のどれかを対象ごとに限定できる。

複数項目が同一トランザクションに属するなら、グループIDとグループ結果を付ける。一括ロールバックを独立した五件の失敗に見せる必要はない。内部ログを公開せずとも、どの項目が同じ決定に含まれるかは示せる。

さらに軽い対策として、順序規則を規範文で定め、作成・更新・削除・失敗・通知を混ぜた例を提示する方法もある。沈黙よりは明らかに良い。不透明キーの方が部分応答や将来の並べ替えに強いが、実装の選択はAPNICにある。必要なのは、いずれか一つの規則を見える形にすることだ。

仕様書もサービスの一部である

APNICは、MyAPNICで行っていた操作を会員が自動化できるよう、このAPIを公開した。テスト環境、ハッカソン、正式提供、製品デモという経緯は、継続的なソフトウェア依存を促している。その段階ではOpenAPIは解説資料ではない。型、SDK、バリデーター、試験、運用手順を生む実際の境界である。

現行文書は、非同期処理、レート制限、トランザクションの限定、問い合わせ先を率直に示している。要求項目との対応欄がないことは、製品が無責任だという証拠ではない。むしろ、APIが長期運用に値するからこそ見える、小さな継ぎ目である。

障害が起きるまで待つ必要はない。結果に、元の要求へ戻る番地を与えればよい。その瞬間、success、failure、notification は人間が推測で並べ直す札ではなく、機械が安全に次の行動を選べる記録になる。

情報源