メインコンテンツまでスキップ

API化の次に来る問題

API化の次に来る問題の結論、主分析、判断材料、前提と限界を一枚にまとめた詳細図

先に結論​

正常として許可した通信だけを通すPositive Securityを厳密にするほど、アプリケーションとセキュリティ設定の不整合が新しい障害になる。アプリへ項目を追加したのにAPI設計を記述するOpenAPIを更新しなければ、正常通信をWAFが止める。共通入口であるGatewayだけを更新すれば、実装が受け付けない入力を公開する。テストだけが古ければ、不整合を検出できない。

対策は、OpenAPI、業務上の判断規則であるPolicy、Infrastructure設定をコード管理するIaC、テストを、同じ変更要求とPull Requestへ結び付けることだ。Pull Requestは、変更を本体へ取り込む前に差分と検査結果を確認する仕組みである。OpenAPIを通信契約の中心に置きつつ、認可、操作順序、副作用、例外は別のPolicyとテストで表す。複数の作業を進めるAI Agentは差分の生成と検査を支援できるが、複数の正本を勝手に書き換える管理者にしてはならない。

この問題は、複数の案内板を持つ施設に似ている。窓口の案内、Webサイト、館内地図、警備員の入館名簿が別々に更新されれば、利用者は新しい部屋へ行けても警備員に止められたり、案内にはあるのに実際の部屋が存在しなかったりする。APIでも、実装、OpenAPI、Gateway、WAF、Testが別々に変わると同じことが起きる。

第1回ではOpenAPIをシステム同士の約束として扱った。第2回では、その約束を使って契約外通信を見つけるPositive Securityを扱った。ここで新しい問題が現れる。正常通信を厳密に定義するほど、約束の更新漏れが正常な利用者を止めるのだ。

本稿の目的は、すべてを一つの巨大Fileへ詰め込むことではない。役割の異なる設計書、Policy、設定、Testを、一つの変更理由と証跡で結ぶことである。技術初学者は「正本」「Pull Request」「CI/CD」という用語を、更新漏れを防ぐ仕組みとして順に追えばよい。

業務要求の変更
      |
      v
契約差分 + Policy差分
      |
      +------> 実装 / 媒介層
      +------> Gateway / WAF / IaC
      +------> Contract / Security / Sequence Test
      |
      v
機械検査 ----> 人間レビュー ----> 段階配備 ----> 実通信との差分監視

図の左端は「なぜ変えるのか」という業務要求である。右へ進むにつれて、契約、実装、設定、Testという具体物へ変わる。機械検査で明らかな不一致を止め、人間が業務上の妥当性を確認し、少しずつ本番へ出し、最後に実通信が設計どおりかを見る。どこか一段だけでは同期は完成しない。

まず、同期ずれを日常の変更で考える​

注文APIへ「置き配希望」という項目を追加する場面を考える。利用者は玄関前、宅配Box、対面などを選ぶ。アプリ画面、API、配送システム、Gatewayの入力検査、Test、利用者向け説明を変える必要がある。

実装だけが先に変わり、OpenAPIとWAFが古いままだと、新しいdeliveryPreference項目は契約外として拒否される。急いでWAFに「この通信は全部通す」という例外を入れると、置き配項目だけでなく、本来拒否すべき未知項目まで通すかもしれない。

反対にOpenAPIだけを更新し、実装が古いままだと、利用者は新機能が使えると思って送信するが、Backendは理解できない。TestもOpenAPIから自動生成されていれば、未実装の機能を前提に失敗する。どれが先でも、関係する成果物を同じ変更としてそろえなければならない。

成果物置き配追加で変わる内容
業務要求選択肢、対象商品、禁止条件、開始日
OpenAPI新しい項目、選択できる値、Error Response
認可・業務Policy誰がいつ変更できるか、出荷後は変更可能か
実装値の保存、配送側への連携、通知
Gateway・WAF新項目を契約内として検証する設定
Test正常値、未知値、権限外、変更期限、再送
運用失敗率、旧App利用者、切戻し条件

同期とは、すべてを同じ技術で作ることではない。この表の行を同じ変更番号で追跡し、必要な行がそろうまで本番へ出さないことなのだ。

厳しい許可型防御ほど同期ずれに弱い​

ブラックリスト型WAFでは、アプリが新しい正常項目を追加しても、既知攻撃に見えなければ通る場合がある。Schemaで未知Propertyを拒否するPositive Securityでは、契約にない正常変更も止める。制御が精密になるほど、変更管理も精密でなければならないのだ。

典型的な不整合は次である。

変更漏れ起きること危険
実装だけ変更GatewayやSchema Validationが新通信を拒否本番障害、例外ルールの乱立
OpenAPIだけ変更未実装Operationや入力が公開契約に現れる誤ったClient生成、期待との不一致
Gatewayだけ変更Backendが想定しない経路やMethodを受信攻撃面拡大、Parser差異
WAFだけ緩和契約外入力が広く通る恒久的な穴、理由不明の例外
認可Policyを更新しない形式は正しいが権限判定が古いBOLA、Function Level Authorization不備
Testを更新しない変更の成否と影響を確認できない回帰、誤った安心

「API仕様を正本にする」という標語だけでは足りない。誰が、どの変更を、どの順序で承認し、どの成果物が一致すれば配備できるかを定義する必要がある。

Positive Securityは「契約にないものを拒否する」ため、契約が古いと正常通信まで拒否する。これは防御が悪いのではなく、防御が設計の不一致を表面化させた状態である。以前は曖昧に通っていた変更が、厳密な境界では止まる。

現場では、本番障害を急いで直すためにWAF例外を追加しがちである。例外自体が常に悪いわけではない。しかし、理由、対象Path、対象Client、期限、Ownerがない例外は、いつまでも残る新しい穴になる。応急処置と恒久対応を分け、例外の失効日までに契約と実装をそろえる。

同期ずれは安全側にも危険側にも倒れる​

同期ずれには、正常通信を止める「厳しすぎるずれ」と、不要な通信を通す「緩すぎるずれ」がある。

実装より防御が古い
  -> 新しい正常通信を拒否
  -> 可用性の問題

防御より実装が古い、または防御だけ緩い
  -> 想定外の入力や経路を許可
  -> セキュリティの問題

どちらも利用者と事業へ影響する。セキュリティ設定を開発と別の後工程にせず、同じ変更の一部として扱う理由がここにある。

OpenAPIは通信契約の正本である​

OpenAPIは、Path、Operation、Parameter、Request Body、Response、Security Schemeなどを標準形式で表す。OpenAPI Specificationは、その記述をドキュメント生成、ClientやServerのコード生成、テストなどへ利用できるとしている。1

この特性を使うと、一つの契約差分から次を派生または検査できる。

  • API ReferenceとClient SDK。
  • Request / Responseの型とValidator。
  • Mock ServerとContract Test。
  • Gatewayへ登録するRouteとMethod。
  • Schema Validationへ渡すProfile。
  • API Inventoryと廃止予定Operation。
  • 互換性差分とChange Log。

ただし、すべてを自動生成する必要はない。製品ごとのGateway設定、Rate Limit、認証連携、段階配備はOpenAPIだけで表し切れない。OpenAPIを共通の入力と検査基準にし、製品固有PolicyはIaCで管理する方が現実的である。

正本は、複数の情報が食い違ったときに、最終的に正しいと扱う情報源である。人事名簿なら人事System、商品価格なら価格管理Systemというように、情報の種類ごとにOwnerと正本を決める。APIのPath、Method、入力、ResponseについてはOpenAPIを正本候補にできる。

「正本にする」とは、OpenAPIを手作業で丁寧に保守するという精神論ではない。変更がOpenAPIにないと実装を取り込めない、OpenAPIにあるOperationが実装されていないとTestが失敗する、Gateway設定が契約と違えば配備が止まる、という機械的な関係を作ることである。

派生と検査を分ける​

OpenAPIから成果物を作る方法には、生成と検査がある。生成は、契約からClient用Codeや入力検査のひな型を作ることだ。検査は、別に作られた実装や設定が契約と一致するかを比べることだ。

すべてを自動生成できれば同期しやすいが、現実には製品固有設定や既存Codeがある。その場合でも、OpenAPIに存在しないRouteがGatewayへ追加されていないか、実装のResponseが契約どおりかを検査できる。生成できないから契約が無意味になるわけではないのだ。

Versionも記録する。どのOpenAPI版から、どのValidator、Test、Gateway設定、Client Libraryを作ったかが分からなければ、障害時に組み合わせを再現できない。成果物へ契約VersionとChange IDを付けることで追跡しやすくなる。

OpenAPIを万能なSingle Source of Truthにしない​

OpenAPIで表せるのは主にHTTP境界である。次は別の正本が必要になる。

対象正本候補理由
通信形状OpenAPIPath、Method、Schema、Response、Security Scheme
複数APIの順序Arazzo、Sequence Test依存、成功・失敗条件、状態遷移
認可と統治Policy as Code、認可モデル主体、対象、関係、職務分離、例外
InfrastructureTerraform等のIaCNetwork、Gateway、WAF、Identity、Log設定
業務の正しさ受入条件、Business Oracle金額、在庫、承認、取消、重複処理
運用判断Runbook、SLO、例外台帳切戻し、影響、Owner、期限、残余リスク

ArazzoはAPI呼出シーケンスと依存関係を表現できるが、そのWorkflowが業務要件を満たすかは別の評価である。Policy as Codeも、書かれたPolicyが正しいことを自動的には保証しない。正本は一つに無理やり統合するのではなく、責任の異なる正本を変更IDで結ぶのだ。

Single Source of Truthは「正しい情報源を一つにする」という考え方である。ただし、システム全体のあらゆる意味をOpenAPI一つへ入れようとすると、かえって責任が曖昧になる。通信の形、権限、Infrastructure、業務結果では、決める人も変更頻度も異なるからである。

たとえば送金APIのOpenAPIには、送金元口座、送金先、金額の形式を書ける。しかし、「100万円を超える送金は二人で承認する」「特定地域への送金は追加確認する」といった業務PolicyをSchemaだけで表すのは難しい。Networkの公開範囲やFirewall設定も別の形式が必要になる。

そこで、正本を情報の種類ごとに分ける。OpenAPIは通信、Policy as Codeは権限、IaCはInfrastructure、受入条件は業務の正しさを持つ。そして、すべてへ同じChange IDを付ける。図書館で本、利用者、貸出記録を別の台帳に持ちながら、同じ識別番号で関係をたどるのに近い。

Business Oracleが必要な理由​

Oracleは、Test結果が正しいかを判定する基準を意味する。Business Oracleは、業務上期待する結果の基準である。APIが200 OKを返し、ResponseがSchemaに合っていても、請求額が一桁違っていれば業務上は失敗である。

在庫を一個減らす、送金元と送金先の残高合計を保つ、取消時に返金と通知を行う、といった期待値を別に定める。技術Testだけでなく、業務担当者が例を確認する必要がある。機械可読な契約は判断を助けるが、業務の正しさを自動的に発見してくれるわけではない。

Policy as Codeで判断を差分にする​

Open Policy Agentは、Policy DecisionをSoftwareから分離するPolicy Engineであり、API、Microservices、Kubernetes、CI/CDなどへ共通Policyを適用できる。Policyをコードとして管理すると、変更差分、Test、Review、RollbackをGit上で扱える。2

たとえば「一般利用者は自分のデータだけ読める」「管理者でも大量Exportは二者承認」という判断は、OpenAPIのSchemaよりPolicy側へ置く。APIはPolicy Decisionへ、主体、Action、対象、Contextを渡す。

{
  "subject": {"id": "u-123", "roles": ["member"]},
  "action": "statements.read",
  "resource": {"ownerId": "u-123", "accountId": "a-456"},
  "context": {"channel": "web", "risk": "low"}
}

ただし、中央Policy Engineへすべてを集めると、可用性、Latency、共有障害、Policy変更の影響範囲が増える。Decision Logに個人情報や機密属性を残す危険もある。Runtimeを責任境界ごとに分け、共通のPolicy Package、Test、署名、配布証跡をControl Planeで揃える設計も検討する。

Policy as Codeは、判断規則を普通の文章だけでなく、機械が評価できるCodeとして管理する方法である。たとえば「本人の口座なら閲覧を許可する」という規則へ、利用者IDと口座Owner IDを渡し、許可または拒否を返す。規則がCodeなら、誰がいつ変えたかを履歴に残し、変更前後のTestを実行できる。

Policy Engineは、その判断を行う専用の仕組みである。アプリ自身のあちこちへ同じ認可条件を書く代わりに、共通の入力形式で問い合わせる。これにより、規則を見つけやすくし、複数Serviceで同じ考え方を共有しやすくなる。

ただし、Policy Engineへ「管理者ならすべて許可」と誤って書けば、一貫して誤った判断が配布される。中央化は正しさを保証するのではなく、変更点と影響範囲を見えるようにする。重要なPolicy変更には、許可される例だけでなく、拒否されるべき例を必ずTestする。

Positive TestとNegative Test​

Positive Testは、許可すべき操作が成功するかを確認する。Negative Testは、拒否すべき操作が本当に失敗するかを確認する。認可では両方が必要である。

Test例期待結果
Positive本人が自分の明細を読む許可
Negative本人が別人の明細を読む拒否
Negative一般利用者が全件Exportする拒否
Positive承認済み管理者が範囲内をExportする許可

許可Testだけでは、機能が動くことしか分からない。拒否Testがあることで、権限を緩める変更や対象条件の欠落を検出しやすくなるのだ。

一つの変更を一つの証跡連鎖にする​

安全な変更単位は、ファイル一つではなく、要求から実通信までの証跡連鎖である。

段階成果物自動検査人間の判断
要求Change ID、受入条件、脅威、禁止事項必須項目、Owner、対象System業務目的、優先度、残余リスク
契約OpenAPI、Arazzo、Policy差分Lint、参照解決、破壊的変更公開範囲、互換性、認可
実装Code、Mediator、IaCBuild、SAST、SCA、Unit Test設計妥当性、例外
検証Contract、Security、Sequence、Load Test期待値比較、Negative TestBusiness Oracle、許容差
配備Artifact、Policy Bundle、Gateway設定署名、環境差分、Canary本番承認、切戻し条件
観測Trace、拒否Log、Inventory差分未知Operation、Error、SLO継続、修正、Rollback

NIST SP 800-218 SSDFは、各SDLCへ統合できる高位のSecure Development Practiceを共通語彙として提示している。NIST SP 800-228はAPIのpre-runtimeとruntime双方の制御を扱う。契約作成だけでなく、開発、配備、実行時保護を一つのLifecycleとして扱う根拠になる。34

証跡連鎖は、変更理由から本番結果までを一本道でたどれる状態である。Change IDを開けば、要求、契約差分、Code差分、Test結果、承認者、配備Version、監視結果が分かる。問題発生時に「何が本番へ出たのか」を推測せずに済む。

SASTは、実行前のSource Codeから弱点を探す検査である。SCAは、利用している外部Libraryや依存関係を調べ、既知の脆弱性や利用条件を確認する検査である。Contract TestはAPI契約との一致、Sequence Testは操作順序、Load Testは負荷への耐性を確認する。これらは同じものを重複検査するのではなく、異なる失敗を探す。

Canary配備は、新しい版をいきなり全利用者へ出さず、一部の通信や利用者だけへ適用する方法である。Error率や応答時間が悪化したら範囲を広げず、Rollbackして以前の版へ戻す。契約と設定を同期しても、実際の負荷や利用方法まで完全には予測できないため、段階配備と観測が必要になる。

証跡は大量のLogではない​

記録を増やすだけでは、判断しやすい証跡にならない。承認者が知る必要があるのは、何が変わるか、どのTestが通ったか、どのTestをしていないか、残る危険は何か、問題時に戻せるかである。

AIは大量の結果を要約できるが、失敗を消したり、未実施を合格へ読み替えたりしてはならない。元のTest結果へたどれるLinkを残し、要約と原データの関係を保つ。証跡は説明のための選別された情報であり、単なるLog置場ではないのだ。

CI/CDで止めるべき不整合​

最低限、次のGateを作る。

  1. OpenAPIが構文と参照を満たす。
  2. 破壊的変更が識別され、Versioningまたは利用者承認がある。
  3. 実装Operationと契約Operationに無断差分がない。
  4. Gateway Route、Method、Schema Profileが契約に対応する。
  5. 認可PolicyのPositive / Negative Testが通る。
  6. 契約外Property、Method、Content-Type、Sizeを拒否する。
  7. BOLA、Tenant越境、権限昇格、業務順序を別Testで確認する。
  8. Originへの直接到達と旧Endpointの再出現を外形検査する。
  9. 生成物と設定にChange ID、Commit、契約Versionを記録する。

CloudflareのSchema Validationが、OpenAPIを検出へつなぎ、観測後にCustom Ruleで強制する構造を持つことは、契約からRuntime Securityへ接続できる具体例である。5 ただし製品へSchemaをUploadした時点で同期が完成するわけではない。Upload元、反映Version、対象Endpoint、強制Rule、Rollbackを追跡する。

CI/CDは、変更を継続的に検査し、Build、Test、配備へ進める仕組みである。ここでいうGateは、次の工程へ進んでよいかを判定する関門である。空港で必要書類がそろわなければ搭乗口へ進めないように、必要な検査が失敗した変更を本番へ出さない。

最初から九項目すべてを完璧に自動化する必要はない。まず、OpenAPIの文法、破壊的変更、実装との差、Gateway Routeとの差という、比較しやすい項目から始める。次に認可と業務順序のTest、外部からの迂回検査を加える。

破壊的変更は、既存Clientが動かなくなる変更である。必須項目の追加、項目の削除、型の変更、意味の変更などが該当する。自動Toolは候補を検出できるが、実際の影響は利用Clientの状況による。Versionを分ける、移行期間を設ける、利用者と合意するといった人間の判断が必要になる。

本番とRepositoryの両方を見る​

Repositoryは、OpenAPI、Code、IaC、Policyなどと変更履歴を保存する場所である。ここにある情報が正しくても、本番へ別の手作業変更が入っていれば状態はずれる。逆に、本番で使われている未知EndpointがRepositoryに存在しない場合もある。

そのため、配備前にはRepository内の成果物同士を比べ、配備後には実通信や実設定と比べる。API Inventoryは、組織が持つAPI、Owner、公開範囲、Versionなどの台帳である。実通信から見つけたOperationとInventoryの差を確認し、無断の追加や廃止漏れを探す。

同期は開発時だけの仕事ではない。Runtime、つまり本番で動いている状態まで含めて初めて閉じるのだ。

AI Agentは変更案と検査役に置く​

AI Agentへ向いているのは、複数成果物の差分を読み、漏れを列挙し、変更案とTestを作り、結果を説明する仕事である。

許可する
  契約差分から影響候補を列挙
  Mediator、IaC、Testの変更案を作成
  互換性、未対応Operation、Policy漏れを検査
  実行結果と証跡をPull Requestへ整理

自動承認させない
  公開機能を増やす
  認可を緩める
  WAF例外を恒久化する
  Legacy Originを公開する
  失敗したSecurity Testを免除する

Agentの提案もSupply Chainの一部である。最小権限、隔離された実行環境、変更可能Repositoryの限定、Secret非開示、署名済みArtifact、二者承認、監査Logを用意する。AIの役割は「全部を同期して本番へ出す」ではなく、「同期していない差分を見つけ、人間が判断できる変更単位へ整える」ことなのだ。

AI Agentは、質問へ一回答えるだけでなく、複数の資料を読み、Toolを使い、手順を進めるAIである。たとえばOpenAPIの差分を読み、影響するGateway設定とTestを探し、変更案をBranchへ作り、検査結果をPull Requestへ整理できる。

ここでBranchは本体から分かれた作業場所、Pull Requestはその差分を人が確認して本体へ取り込む手続きである。AIに直接本体を書き換えさせず、Branch上の提案として出させれば、差分、Test、承認を確認できる。

AIへ渡す権限を小さくする​

AIの誤りをゼロにすることは難しい。そこで、誤っても影響が広がらない権限設計を行う。

  • 読取り対象を、必要なRepositoryと資料へ限定する。
  • 書込みは提案用Branchだけにし、本番設定へ直接触れさせない。
  • PasswordやAPI KeyなどのSecretを入力へ含めない。
  • Testは隔離環境で実行し、外部Networkや本番Dataへの接続を制限する。
  • 配備は署名済みArtifactと人間承認を確認するPipelineだけが行う。
  • AIが作った要約から、元の差分とTest結果へたどれるようにする。

Supply Chainは、外部Library、開発Tool、Build、配布など、Softwareが利用者へ届くまでの経路である。AIが作るCodeや設定もこの経路の一部になる。便利な生成元として例外扱いせず、誰が何を生成し、どの検査を通ったかを記録する。

AIへ任せない判断​

公開Endpointの追加、認可の緩和、WAF例外の恒久化、Security Testの免除は、事業と利用者へ直接影響する。AIは影響候補を整理できるが、許容する責任までは持てない。変更理由、残るRisk、期限、Rollbackを人間が確認する。

AIを万能管理者にせず、更新漏れを見つける目と、変更案を整える手として使う。これが速度と統制を両立しやすい置き場所なのだ。

小さく始める導入手順​

全社の全APIを一度に同期させようとすると、台帳作りだけで止まりやすい。一つの低リスクAPIと一つの変更を選び、端から端まで通す。

  1. 対象APIのOwnerと利用Clientを確認する。
  2. 現在の実通信からPath、Method、入力を集める。
  3. OpenAPIと実装の差を直し、通信契約の正本を決める。
  4. Gateway RouteとSchema検証を観測状態で接続する。
  5. OpenAPI、実装、IaC、Testを同じPull Requestへ入れる。
  6. 文法、破壊的変更、契約差分をCIで止める。
  7. 一部へ配備し、拒否Log、Error、応答時間を確認する。
  8. Change IDから要求と本番結果までたどれるか確認する。

最初の評価指標は、生成したCode量ではない。変更時の手作業転記数、同期漏れの検出時間、期限切れ例外数、契約にないOperation数、Rollbackにかかった時間を見る。仕組みが複雑になっただけなら改善とは言いにくい。

一つの変更を最初から最後まで追う​

顧客情報APIへ「連絡方法の希望」を追加する例で、同期の流れを具体化する。利用者はMail、電話、郵送から選ぶ。単純な選択項目だが、業務、Data、権限、画面、API、Legacy連携へ影響する。

要求をChange IDへ登録する​

変更にはCHANGE-2048のような識別子を付ける。目的は「顧客が希望する連絡方法で通知すること」、禁止事項は「同意のない方法へ販促連絡を送らないこと」、開始日は次の月初とする。API Owner、Data Owner、業務Ownerを登録する。

Change IDは単なる番号ではない。後から番号を検索すれば、なぜ変更したか、誰が判断したか、何が本番へ出たかをたどれる入口にする。

契約とPolicyを分けて変更する​

OpenAPIにはcontactPreferenceという項目と、email、phone、postalという選択肢を追加する。古いClientが項目を送らなくても動くよう、初期段階では任意項目にする。Responseにも現在値を含める。

一方、「販促目的で使ってよいか」「本人以外が変更できるか」はSchemaの選択肢だけでは表せない。認可Policyと同意管理の業務Ruleを別に変更する。OpenAPI変更だけを見て作業完了としない。

影響する成果物を列挙する​

AI AgentはRepositoryとInventoryを読み、次の影響候補を挙げる。

  • Web画面とMobile Appの入力欄。
  • OpenAPIのRequestとResponse Schema。
  • 顧客Dataを保存するDatabase。
  • Legacy CRMへ値を変換する媒介層。
  • 本人だけが変更できる認可Policy。
  • GatewayのSchema Profile。
  • Contract、Security、Sequence Test。
  • Data保持と同意の監査Log。
  • 利用者向け説明と問い合わせ手順。

AIの一覧は出発点である。業務担当者は、電話連絡を外部Call Centerが行うことや、郵送だけ夜間Batchで処理することを追加するかもしれない。Repositoryにない現実を人間が補う。

Pull Requestで差分をまとめる​

OpenAPI、Policy、媒介層、IaC、Testの変更を、同じChange IDを持つPull Request群へまとめる。Repositoryが分かれていて一つのPull Requestにできない場合も、相互Linkと配備順序を記録する。

ReviewではFile名の一覧だけでなく、意味の差分を示す。「外部入力項目が一つ増える」「本人だけ更新可能」「旧Clientは未指定でも動く」「CRM変換は次回Releaseまで行わない」といった説明を添える。

CI/CDのGateで不一致を止める​

LintはOpenAPIの文法を確認する。互換性検査は、任意項目追加で旧Clientを壊さないかを見る。Contract TestはRequestとResponse、Negative Testは未知値、Security Testは他人による変更拒否を確認する。

媒介層のTestでは、phoneがLegacyのCode2へ正しく変換されるかを見る。Business Oracleでは、同意のない販促連絡が作られないことを確認する。どれかが失敗すれば、本番配備へ進めない。

一部へ配備して観測する​

最初は社内利用者や少数の顧客だけへ新機能を出す。古いAppからのError、Schema拒否、保存失敗、CRM連携失敗、連絡件数を観測する。問題があれば、項目を表示しない、以前のVersionへ戻すなど、決めたRollbackを行う。

配備後に、実通信でcontactPreferenceが契約どおり使われているか確認する。手作業でGatewayを緩めた形跡や、未知値がないかも見る。Change IDへ結果を結び、変更Loopを閉じる。

この例では、AIは影響候補の列挙、差分案、Test案、Evidence要約を支援できる。しかし、同意の意味、旧Clientの移行期限、未確認Riskの受容はOwnerが決める。

Team間の責任を明確にする​

同期問題はToolだけでは解決しない。「API TeamがWAF Teamへ連絡するはず」「Securityが認可も見るはず」という暗黙の分担が漏れを生む。成果物ごとにOwnerとReview責任を決める。

役割主な責任単独で決めないこと
業務Owner目的、受入条件、業務例外技術的な安全性の合否
API OwnerOpenAPI、互換性、利用ClientData利用目的、Risk受容
Security認証、認可、防御、Security Test業務上許可すべき操作
Data Owner収集目的、範囲、保持、削除APIの配備方法
PlatformGateway、WAF、IaC、Pipeline各業務の認可意味
運用監視、SLO、Incident、Rollback公開範囲の恒久的な拡大

小規模組織では一人が複数の役割を持ってもよい。ただし、「誰がどの観点を確認したか」を残す。全員承認という曖昧な状態は、実際には誰も責任を持たない状態になりやすい。

手作業変更を完全に禁止できない場合​

Incident対応で、管理画面から緊急変更することはある。その場合は、手作業変更を隠さず、Change ID、理由、実施者、期限を記録する。復旧後にIaCへ取り込み、本番設定とRepositoryを一致させる。

この作業をReconciliation、つまり望ましい状態と実状態の差を戻す作業として扱う。AIは差分を検出してIaC案を作れるが、緊急設定を正本へ自動採用してはならない。不正な変更まで正しいものとして保存する危険があるからだ。

よくある同期対策の失敗​

会議と手順書だけで同期する​

担当者が毎回忘れず連絡する前提は、変更頻度が上がるほど崩れる。比較できる差分はCIで検査し、人間は意味の判断へ集中する。

一つの巨大Repositoryへ集めれば解決する​

Fileを同じ場所へ置いても、Owner、配備順序、Version関係がなければ同期しない。別RepositoryでもChange IDとGateで結べる。物理的な一か所化と、意味の一貫性は別である。

Testを生成したから十分とする​

実装とTestを同じAIが同じ前提から作ると、同じ誤りを共有する可能性がある。既存の正しい例、業務Oracle、独立したSecurity Test、実通信を組み合わせる。

例外を最速の解決方法にする​

同期ずれのたびにWAFやPolicyを広く緩めると、Positive Securityが崩れる。例外は対象を狭くし、期限と恒久修正を付ける。

配備成功で同期完了とする​

Pipelineが成功しても、本番で旧Clientが失敗したり、手作業設定が残ったりする。実通信、Error、Inventoryとの差まで確認する。

非技術者が変更会議で確認すること​

  1. 何の業務要求で変更するのか。
  2. API契約だけでなく、権限と業務規則も変わるか。
  3. 実装、Gateway、WAF、Testのどこが影響を受けるか。
  4. 正常な利用者を止める可能性と、制御を緩める可能性の両方を見たか。
  5. AIの提案を独立したToolと責任者が検査したか。
  6. どのTestを実施し、何を未確認のまま残すか。
  7. 一部配備とRollbackの条件は何か。
  8. 本番の実通信が契約と一致したことを後で確認するか。

専門用語をすべて読めなくても、この八つへの答えが同じChange IDに集まっていれば、変更の筋道を追える。

この回で覚えておくこと​

  • Positive Securityを厳密にするほど、契約と実装の更新漏れが障害になる。
  • OpenAPIは通信契約の正本にできるが、認可、Infrastructure、業務結果には別の正本が必要である。
  • 複数の正本は、一つのChange IDとPull Requestで関係付ける。
  • CI/CDのGateで、文法、破壊的変更、実装、Gateway、Policy、Testの不一致を止める。
  • 配備後は実通信とInventoryを確認し、Repositoryだけを現実だと思わない。
  • AI Agentは差分発見と変更案作成に使い、本番反映とRisk受容は人間に残す。

精密な防御は、精密な変更管理と一組である。契約を強くするだけでなく、契約が変わるたびに関係する設定とTestを一緒に動かす仕組みを作るのだ。

前後の記事​

用語集​

用語平易な説明
Positive Security正常として許可する通信を先に定義し、それ以外を検出または拒否する考え方。
OpenAPIAPIの窓口、入力、出力、認証方法などを、人間とコンピュータの双方が読める形で記述する標準仕様。
Single Source of Truth（正本）複数の資料が食い違わないよう、最終的に正しいと扱う情報源を一つ定める考え方。
Policy as Code認可やセキュリティ判断のルールを、レビューや自動テストができるコードとして管理する方法。
OPA（Open Policy Agent）アプリからPolicy判断を分離し、共通ルールとして評価できるオープンソースのPolicy Engine。
IaC（Infrastructure as Code）Gateway、Network、Serverなどの構成を、再現可能なコードで管理する方法。
CI/CD変更の検査、Test、Build、Releaseを継続的に自動化する仕組み。
Pull Request変更を本体へ取り込む前に、差分、テスト結果、承認をまとめて確認する仕組み。
Lint記述ミスや決められた書式への違反を、機械的に検査すること。
Contract／Security／Sequence／Load／Negative Test順に、契約適合、安全性、操作順序、負荷、拒否すべき異常入力を確認するテスト。
Arazzo複数のAPIを呼ぶ順番や、前の結果を次へ渡す関係を記述する仕様。
Business Oracle業務上の正しい結果を判定する基準。Schemaに合うかだけでは分からない金額、在庫、副作用などを確認する。
Mediator新しいAPIとLegacyの間で、データ形式や操作を変換する仲介層。
Artifact／Policy BundleBuildや生成で作られ、配布される成果物。Policy Bundleは実行に必要なルールをまとめた成果物。
Canary Release一部の利用者や通信だけへ新しい版を出し、問題がないか確認してから範囲を広げる方法。
Rollback問題が起きた変更を取り消し、以前の正常な状態へ戻すこと。
SAST／SCASASTはソースコードの弱点を調べる検査。SCAは利用している外部Libraryや依存関係の脆弱性を調べる検査。
Trace／SLOTraceは一つの要求が複数システムを通る流れの記録。SLOは応答時間や成功率など、目標とするService品質。
Change ID契約、実装、Policy、Test、Releaseの変更を同じ案件として追跡するための識別子。
AI Agent情報を読み、複数の手順やTool利用を組み合わせて、変更案や検査結果を作るAI。
Supply Chain開発Tool、外部Library、Build、配布など、Softwareが利用者へ届くまでの一連の経路。

参考資料​

Footnotes​

  1. OpenAPI Initiative, OpenAPI Specification v3.2.0。HTTP APIの標準記述と、ドキュメント、コード生成、テスト等への利用。https://spec.openapis.org/oas/latest.html ↩

  2. Open Policy Agent, OPA Documentation。Policy DecisionをSoftwareから分離し、複数のシステムへ適用するPolicy Engineの公式文書。https://www.openpolicyagent.org/docs ↩

  3. NIST, SP 800-218: Secure Software Development Framework Version 1.1（2022年2月3日、Final）。SDLCへ統合するSecure Software Development Practice。https://csrc.nist.gov/pubs/sp/800/218/final ↩

  4. NIST, SP 800-228: Guidelines for API Protection for Cloud-Native Systems（2025年6月、2026年3月13日更新）。APIのpre-runtimeとruntime制御。https://csrc.nist.gov/pubs/sp/800/228/upd1/final ↩

  5. Cloudflare, Schema validation。OpenAPI Schemaによる違反検出とCustom Rulesによる強制の分離。https://developers.cloudflare.com/api-shield/security/schema-validation/ ↩