メインコンテンツへスキップ
見出し画像

AI、変更しやすいAPI設計とは?|L5-016

    【AI実装型座談会|RenaとMAIのデジタル探検編】
    LEVEL 5|ENGINEER・専門設計編
    L5-016|AI、変更しやすいAPI設計とは?
    AI, What Makes an API Easy to Change Without Breaking Its Users?

    制作基準|RM-ACF v1.2・独立完結型
    記事版|v2.0・内容精査/API契約/後方互換性/実装検証・完全改訂版
    専門用語|API設計・互換性
    Technical Keywords|API Design / API Contract / Backward Compatibility / Breaking Change / Schema Evolution / HTTP / OpenAPI / Consumer Contract / Versioning / Regression Testing / HEAD / Problem Details / Migration Strategy

    講師|MAI(Mind Artificial Intelligence)
    進行・質問・設計・反論・検証|Rena
    学習対象|Web APIの設計、変更管理、互換性、契約テスト
    学習目標|既存利用者への影響を把握し、変更できる部分と維持すべき契約を区別し、検証可能なAPI変更を設計する
    実験環境|Python 3.13.5
    コード対応|Python 3.10以降を想定
    旧版回帰テスト|61件成功
    改訂版自動テスト|108件成功
    追加試験|47件
    OpenAPI|3.1形式・4パス・GET/HEAD計8操作
    JSON Schema例示検証|4種類成功
    実際のAPI公開・移行|未実施

    ──────────────────
    ■新しい機能を追加したら、古いアプリが動かなくなった

    火曜日の午後。Renaは、小さな図書情報サービスの改良を進めていた。

    スマートフォンで本の題名や著者名を確認できるサービスだ。

    机の上には、開発用のパソコンとタブレットが並んでいた。

    「ねえAI、今の図書情報APIを、もう少し便利にしたいんだ」

    全高50センチの白とオレンジの小さなAIロボット、MAIが青いデジタルの目を光らせた。

    MAI:「どのような変更を考えていますか?」

    「今は著者が一人しか登録できないんだけど、編集者や翻訳者も表示できるようにしたいの」

    MAI:「現在の応答形式を見せてください」

    Renaは画面を開いた。

    {
      "id": "bk-001",
      "title": "星の手帖",
      "author": "青木遥"
    }

    「これが今の形だよ」

    MAI:「本の識別番号、題名、著者名ですね」

    「うん。だからauthorをcontributorsに変えて、複数の人を登録できるようにするの」

    Renaは新しい形式を作成した。

    {
      "id": "bk-001",
      "title": "星の手帖",
      "contributors": [
        {
          "name": "青木遥",
          "role": "author"
        }
      ]
    }

    「これなら、いろいろな役割の人を登録できるよね」

    MAI:「表現できる情報を増やす方向としては合理的です。ただし、既存のアプリへの影響は確認しましたか?」

    「項目名と中身の形を変えただけだよ?」

    MAI:「以前のアプリが、authorという項目を使っている可能性があります」

    Renaは、古いアプリを起動した。

    画面に本の題名は表示された。

    しかし、著者名のところでエラーが発生した。

    「えっ、どうして?」

    MAI:「新しいデータには、以前のauthorが存在しないためです」

    「でも、新しい設計の方が便利なのに!」

    MAI:「新しい機能を実現できることと、以前の利用者が使い続けられることは別です」

    「じゃあ、便利にするたびに古いアプリが壊れちゃうの?」

    MAI:「そうならないようにするための考え方が、API設計と互換性です」

    Renaは二つのデータ形式を見比べた。

    「ねえAI、変更しやすいAPI設計って、どういうものなの?」

    MAI:「変更してよい部分と、維持すべき約束を区別できる設計です」

    ──────────────────
    ■APIとは何か?

    API(Application Programming Interface)は、ソフトウェアが別のソフトウェアの機能や情報を利用するための接点です。

    Web APIでは、HTTPなどを使って要求と応答をやり取りできます。

    例えば、今回の図書情報サービスでは、

    スマートフォンアプリ
            │
            │ GET /v1/books/bk-001
            ▼
          Web API
            │
            ▼
     図書情報を取得する処理
            │
            │ JSON形式の応答
            ▼
    スマートフォンアプリ

    という流れになります。

    情報を提供する側をProvider、利用する側をConsumerと呼びます。

    Provider|図書情報APIを提供する側。

    Consumer|図書情報を取得・表示するアプリ側。

    「ねえAI、APIはデータを送る仕組みというだけじゃないんだね」

    MAI:「はい。どのような要求を受け付け、何を返すかという取り決めも含みます」

    ──────────────────
    ■API契約とは何か?

    API契約(API Contract)は、提供側と利用側の間で前提となる約束です。

    例えば、

    ・どのURLを使用するか。
    ・どのHTTPメソッドを使うか。
    ・どの入力項目が必要か。
    ・どの応答項目が必須か。
    ・データの型は何か。
    ・項目の意味や単位は何か。
    ・エラー時には何が返るか。
    ・認証や利用制限はどうなっているか。
    ・どのバージョンをいつまで利用できるか。

    などが契約に関係します。

    今回の旧APIでは、次のように定義します。

    HTTP Method:
    GET
    
    Path:
    /v1/books/{book_id}
    
    成功時:
    HTTP 200
    
    Content-Type:
    application/json
    
    必須項目:
    id       string
    title    string
    author   string

    「アプリは、この契約を前提に作られているんだね」

    MAI:「その通りです」

    つまり、APIの内部処理を変更することと、外部へ公開した契約を変更することは別です。

    Internal Implementation ≠ External Contract.

    内部実装と外部契約は同じではありません。

    ──────────────────
    ■変更しやすいAPIには二つの側面がある

    MAI:「変更容易性には、少なくとも二つの側面があります」

    内部変更容易性|Internal Modifiability

    APIの内部プログラム、データ構造、データベースなどを変更しやすいこと。

    外部互換性|External Compatibility

    APIを変更しても、以前の契約を利用しているクライアントが、必要な動作を続けられること。

    「ねえAI、中身を変更しやすければいい、というわけじゃないんだね」

    MAI:「はい」

    サーバーのプログラムを一行修正しただけでも、数千のクライアントが利用している必須項目を削除してしまえば、大きな影響が出る可能性があります。

    反対に、内部のデータベースを大幅に変更しても、外部契約が維持されていれば、利用者へ影響を出さずに変更できる場合があります。

    Small Code Change ≠ Small User Impact.

    コードの変更量と、利用者への影響は比例するとは限りません。

    ──────────────────
    ■後方互換性とは何か?

    後方互換性(Backward Compatibility)は、新しいAPIの実装でも、以前の契約に従う利用者が継続して利用できる性質です。

    例えば、旧クライアントが次の処理を使っていたとします。

    author_name = book["author"]

    この時、APIがauthorを返さなくなると、そのクライアントは失敗する可能性があります。

    しかし、新しいAPIでauthorを維持したままlanguageを追加するなら、以前の使い方を継続できる場合があります。

    変更前:

    {
      "id": "bk-001",
      "title": "星の手帖",
      "author": "青木遥"
    }

    変更後:

    {
      "id": "bk-001",
      "title": "星の手帖",
      "author": "青木遥",
      "language": "ja"
    }

    「以前の項目が残っているから、古いアプリも使いやすいんだね」

    MAI:「はい。ただし、項目の追加が常に安全だとは限りません」

    ──────────────────
    ■項目の追加だけでも壊れることがある

    例えば、次のような旧クライアントを考えます。

    if set(book) != {"id", "title", "author"}:
        raise ValueError("Unexpected response shape")

    このクライアントは、三つの項目以外が存在するとエラーになります。

    そのため、languageを追加しただけでも失敗します。

    一方、必要な三項目だけを読み取るクライアントなら、正常に動作する可能性があります。

    「同じ変更でも、利用する側の作り方で結果が違うんだね」

    MAI:「はい」

    ただし、ここにはさらに重要な区別があります。

    API契約で、未知の応答項目を許容すると定めていた場合、追加項目を拒否する旧クライアントの方が、その契約に適合していない可能性があります。

    つまり、

    実際にアプリが失敗することと、

    API提供側が契約違反をしたこと

    は、必ずしも同じではありません。

    Observed Failure ≠ Proven Contract Violation.

    失敗が観測されたことだけで、提供側の契約違反が証明されたわけではありません。

    これは、変更の原因調査で重要な区別です。

    ──────────────────
    ■破壊的変更とは何か?

    破壊的変更(Breaking Change)は、既存の契約や利用方法に対して互換性を失わせる変更です。

    典型例を整理します。

    変更想定される影響必須項目の削除旧クライアントが値を取得できない項目名の変更以前の名称を参照する処理が失敗文字列から配列への型変更データ処理の前提が変わる新しい必須入力の追加古い要求が拒否されるnullの追加値の存在を前提とする処理が失敗列挙値の追加未知の値を扱えない処理が失敗認証方式の変更旧クライアントが接続できなくなる意味や単位の変更エラーが出なくても結果を誤る

    「ねえAI、データの形が同じでも、意味が変わったら問題なんだね」

    MAI:「その通りです」

    例えば、priceという項目が、以前は税抜価格を表していたとします。

    同じ項目名のまま税込価格へ変更すると、旧クライアントが税額を二重に加算してしまうかもしれません。

    JSONの項目名も型も変わっていません。

    しかし、利用者が期待していた意味が変わっています。

    Schema Compatibility ≠ Semantic Compatibility.

    データ構造の互換性と、データの意味の互換性は別です。

    ──────────────────
    ■APIの互換性を六つの領域で考える

    MAI:「変更の影響を見落とさないために、API契約を六つの領域へ分けます」

    1|要求契約

    URL、HTTPメソッド、入力パラメータ、必須条件。

    2|応答契約

    項目名、型、必須項目、任意項目、nullの扱い。

    3|意味契約

    金額の単位、日時の解釈、並び順、値の意味。

    4|エラー契約

    HTTPステータス、エラーコード、エラー本文。

    5|運用契約

    認証、権限、利用制限、応答時間、提供条件。

    6|移行契約

    バージョン、非推奨の告知、停止時期、移行方法。

    「JSONの形だけ調べても、全部の互換性は分からないんだね」

    MAI:「はい。形式が同じでも、意味や運用条件が変われば利用者に影響する場合があります」

    ──────────────────
    ■今回の設計課題を決める

    今回の教材では、架空の図書情報APIを設計します。

    内部の図書データは三冊です。

    bk-001|星の手帖
    bk-002|海辺の地図
    bk-003|Small Garden

    外部へ提供する契約は、次の二種類とします。

    v1|旧クライアント向け

    必須項目:

    id、title、author。

    新しいlanguageは、追加可能な任意項目として扱います。

    v2|新しいクライアント向け

    必須項目:

    id、title、contributors、language。

    contributorsには、関係者の名前と役割を持つオブジェクトを配列で格納します。

    ただし、今回の実装が実際に返す関係者は、すべてauthor一人です。

    編集者や翻訳者など、複数の関係者を実際に登録・変更する機能までは実装していません。

    「新しい構造を表現できることと、実際に複数の関係者を管理できることも別なんだね」

    MAI:「はい」

    ──────────────────
    ■v1を残してv2を提供する

    今回の設計では、次の二つのAPIを併存させます。

    旧クライアント
           │
           ▼
    GET /v1/books/{id}
           │
           ▼
    id / title / author
    
    
    新クライアント
           │
           ▼
    GET /v2/books/{id}
           │
           ▼
    id / title / contributors / language

    重要なのは、新しいv2を公開しても、旧クライアントを自動的にv2へ切り替えないことです。

    また、v1とv2は外部から区別できるAPIバージョンです。

    今回のプログラムで使うbaselineとexpandedは、同じv1の変更前後を教材内で再現するための設定であり、実際の公開履歴ではありません。

    API Version ≠ Simulated Release State.

    APIバージョンと、実験用の変更状態は別です。

    ──────────────────
    ■APIの変更前後を比較する

    状態A|v1・変更前

    {
      "id": "bk-001",
      "title": "星の手帖",
      "author": "青木遥"
    }

    状態B|v1・項目追加後

    {
      "id": "bk-001",
      "title": "星の手帖",
      "author": "青木遥",
      "language": "ja"
    }

    状態C|v2・新構造

    {
      "id": "bk-001",
      "title": "星の手帖",
      "contributors": [
        {
          "name": "青木遥",
          "role": "author"
        }
      ],
      "language": "ja"
    }

    変更AからBでは、既存項目を維持しています。

    変更BからCでは、authorを削除し、contributorsへ変更しています。

    今回の設計では、Cをv1へ上書きせず、v2として別に提供します。

    ──────────────────
    ■変更の正しさを、利用者との関係で定義する

    「ねえAI、APIの互換性って、式で考えることもできるの?」

    MAI:「はい。厳密に考えるためには、利用者の期待と変更後の動作を対応させる必要があります」

    今回の教材では、次のように考えます。

    旧APIを利用できていたクライアントをCとします。

    旧APIの契約をK₁、新しい実装をP₂とします。

    そして、

    CがK₁で認められた使い方を続けた時、

    P₂がその契約で保証された動作を満たすなら、対象範囲で互換性があると判断します。

    概念的には、

    Compatibility(P₂, C, K₁) = True

    です。

    ただし、これは今回の教材で互換性を説明するための記法であり、標準化されたAPI互換性の公式ではありません。

    また、すべての実在クライアントについて、この式が成立することを確認したわけではありません。

    「契約を決めないまま、互換性があるとかないとか言っても曖昧なんだね」

    MAI:「はい。何に対する互換性なのかを明確にする必要があります」

    ──────────────────
    ■HTTPの動作も契約に含まれる

    今回のAPIでは、情報取得のためにGETを使用します。

    GET /v1/books/bk-001

    また、HEADにも対応します。

    HEADは、GETと対応する応答のステータスや表現メタデータを取得するためのメソッドです。

    ただし、HTTP応答本文は送信しません。

    例えば、GETなら本の情報が返ります。

    HEADなら、対応するステータスやヘッダーを返し、本文は送りません。

    GET /v1/books/bk-001
    
    HTTP 200
    Content-Type: application/json
    
    {"id":"bk-001", ...}
    HEAD /v1/books/bk-001
    
    HTTP 200
    Content-Type: application/json
    Content-Length: ...
    (本文なし)

    「ねえAI、HEADでも、取得する本の内容は同じように考えるんだね」

    MAI:「はい。ただし、ネットワーク上では本文を転送しません」

    今回の改訂では、このHEADの動作を追加しました。

    ──────────────────
    ■405エラーではAllowヘッダーも必要

    HTTP 405 Method Not Allowedは、対象リソースで要求されたメソッドが許可されていない場合に使用するステータスです。

    RFC 9110では、405の応答にAllowヘッダーを含めることが要求されています。

    今回のAPIでは、GETとHEADだけを対応メソッドとします。

    したがって、POSTなどを受け取った場合は、

    HTTP 405 Method Not Allowed
    
    Allow: GET, HEAD

    を返します。

    「前のプログラムではGETだけになっていたよね」

    MAI:「はい。改訂版ではHEADの対応とAllowヘッダーを整合させました」

    さらに、存在しないURLに対してPOSTが来た場合も、今回の設計では404と405を区別します。

    Unknown Resource ≠ Unsupported Method.

    存在しないリソースと、存在するリソースで許可されないメソッドは別です。

    ──────────────────
    ■クエリパラメータの意味と書式を揃える

    今回の一覧APIでは、次の要求を受け付けます。

    GET /v1/books?limit=2

    limitは、今回の教材では1、2、3のいずれか一つだけです。

    例えば、

    limit=1
    limit=2
    limit=3

    は受け付けます。

    しかし、

    limit=0
    limit=4
    limit=01
    limit=+2
    limit=2.0
    limit=1&limit=2

    などは不合格にします。

    ここで注意したいのは、数値としての意味と、HTTP要求で使える文字列の形式は別であることです。

    前稿のOpenAPI記述ではlimitを整数型として説明していました。

    しかし、実装では数値への変換以前に、1文字の半角数字という書式を要求していました。

    この差をなくすため、改訂版のOpenAPIでは、limitを文字列型として記述し、許容する文字を正規表現で明示しています。

    name: limit
    in: query
    required: false
    schema:
      type: string
      pattern: '^[1-3]$'

    なお、URLのパーセントエンコードはデコードしてから検証します。

    そのため、デコード結果が許容された文字列になる場合は、受け付ける設計です。

    Numeric Meaning ≠ Lexical Representation.

    数値としての意味と、入力された文字列の形式は別です。

    ──────────────────
    ■エラー応答も構造化する

    本が存在しない場合には、HTTP 404を返します。

    例えば、

    GET /v1/books/bk-999

    です。

    エラーの本文には、Problem Details形式を使用します。

    {
      "type": "about:blank",
      "title": "Not Found",
      "status": 404,
      "detail": "Book not found"
    }

    これはRFC 9457に基づく基本的な表現です。

    今回の教材では、次のステータスを主に使用します。

    HTTPステータス意味200取得成功400不正な要求404対象が見つからない405許可されないメソッド

    「成功した時だけじゃなくて、失敗した時の応答も約束なんだね」

    MAI:「はい」

    なお、エラー本文に内部の秘密情報や、公開する必要のない実装詳細を含めるべきではありません。

    ──────────────────
    ■完成版Pythonプログラム v2.0

    ファイル名|L5_016_api_contract_lab_v2.py

    対応|Python 3.10以降
    検証環境|Python 3.13.5
    追加ライブラリ|不要
    外部通信|なし
    ローカルHTTP|任意で127.0.0.1上に起動
    データ保存|なし
    認証・TLS・本番公開|未対応

    以下が、検証に使用した完成版プログラムです。

    """L5-016 API contract laboratory v2.0 | Python >= 3.10, stdlib only.
    
    Only fictional, static records. 127.0.0.1 HTTP opt-in, no persistence,
    authentication, authorization, TLS, rate limits or public deployment.
    The release="baseline"/"expanded" switch simulates API evolution; it is
    not a historical deployment or an API version. HEAD mirrors GET headers and
    status but transfers no message body.
    """
    from dataclasses import dataclass
    import json
    import re
    import sys
    from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
    from urllib.parse import parse_qsl, urlsplit
    
    BOOKS = (
        {"id": "bk-001", "title": "星の手帖", "author": "青木遥", "language": "ja"},
        {"id": "bk-002", "title": "海辺の地図", "author": "森玲奈", "language": "ja"},
        {"id": "bk-003", "title": "Small Garden", "author": "K. Ito", "language": "en"},
    )
    ROUTE = re.compile(r"/(v1|v2)/books(?:/(bk-[0-9]{3}))?\Z")
    LIMIT = re.compile(r"[1-3]\Z")
    ALLOWED_METHODS = "GET, HEAD"
    
    
    @dataclass(frozen=True)
    class Reply:
        status: int
        content_type: str
        body: dict
        allow: str | None = None
    
        def encoded(self) -> bytes:
            return json.dumps(
                self.body,
                ensure_ascii=False,
                separators=(",", ":")
            ).encode("utf-8")
    
    
    def problem(
        status: int,
        title: str,
        detail: str,
        allow: str | None = None
    ) -> Reply:
        """RFC 9457 about:blank core members."""
        return Reply(
            status,
            "application/problem+json",
            {
                "type": "about:blank",
                "title": title,
                "status": status,
                "detail": detail,
            },
            allow,
        )
    
    
    def represent(book: dict, version: str, release: str) -> dict:
        """Separate internal data from external response contracts."""
        if version == "v1":
            data = {
                key: book[key]
                for key in ("id", "title", "author")
            }
    
            if release == "expanded":
                data["language"] = book["language"]
    
            return data
    
        if version == "v2":
            return {
                "id": book["id"],
                "title": book["title"],
                "contributors": [
                    {
                        "name": book["author"],
                        "role": "author",
                    }
                ],
                "language": book["language"],
            }
    
        raise ValueError("Unknown version")
    
    
    def dispatch(
        method: object,
        target: object,
        release: str = "expanded",
    ) -> Reply:
        """Pure bounded request handler; no I/O or data writes."""
    
        if release not in ("baseline", "expanded"):
            raise ValueError("Unknown simulated release")
    
        if type(method) is not str or type(target) is not str:
            return problem(
                400,
                "Bad Request",
                "Request method and target must be strings",
            )
    
        if (
            len(target) > 2048
            or not target.startswith("/")
            or "#" in target
            or any(ord(ch) < 32 or ord(ch) > 126 for ch in target)
        ):
            return problem(
                400,
                "Bad Request",
                "Invalid request target",
            )
    
        try:
            url = urlsplit(target)
    
            if url.scheme or url.netloc:
                return problem(
                    400,
                    "Bad Request",
                    "Only origin-form targets are supported",
                )
    
            match = ROUTE.fullmatch(url.path)
    
            if match is None:
                return problem(
                    404,
                    "Not Found",
                    "Endpoint not found",
                )
    
            if method not in ("GET", "HEAD"):
                return problem(
                    405,
                    "Method Not Allowed",
                    "Only GET and HEAD are supported",
                    ALLOWED_METHODS,
                )
    
            query = parse_qsl(
                url.query,
                keep_blank_values=True,
                strict_parsing=True,
                max_num_fields=2,
                errors="strict",
            )
    
        except (ValueError, UnicodeError):
            return problem(
                400,
                "Bad Request",
                "Malformed request target or query",
            )
    
        version, book_id = match.groups()
    
        if book_id is not None:
            if query:
                return problem(
                    400,
                    "Bad Request",
                    "Item endpoint has no query parameters",
                )
    
            book = next(
                (b for b in BOOKS if b["id"] == book_id),
                None,
            )
    
            if book is None:
                return problem(
                    404,
                    "Not Found",
                    "Book not found",
                )
    
            return Reply(
                200,
                "application/json",
                represent(book, version, release),
            )
    
        if not query:
            limit = len(BOOKS)
    
        elif (
            len(query) == 1
            and query[0][0] == "limit"
            and LIMIT.fullmatch(query[0][1]) is not None
        ):
            limit = int(query[0][1])
    
        else:
            return problem(
                400,
                "Bad Request",
                "Invalid, unknown or repeated query parameter",
            )
    
        items = [
            represent(book, version, release)
            for book in BOOKS[:limit]
        ]
    
        return Reply(
            200,
            "application/json",
            {
                "items": items,
                "count": len(items),
            },
        )
    
    
    def old_tolerant_client(reply: Reply) -> str:
        """Read required v1 fields; ignore extra fields."""
        if reply.status != 200:
            raise ValueError("Request did not succeed")
    
        book = reply.body
    
        for field in ("id", "title", "author"):
            if type(book.get(field)) is not str:
                raise ValueError(
                    f"Missing/wrong v1 field: {field}"
                )
    
        return f"{book['title']} / {book['author']}"
    
    
    def old_strict_client(reply: Reply) -> str:
        """Counterexample: require exactly three v1 fields."""
        if set(reply.body) != {"id", "title", "author"}:
            raise ValueError("Unexpected response shape")
    
        return old_tolerant_client(reply)
    
    
    class LocalHandler(BaseHTTPRequestHandler):
        """Minimal localhost teaching handler, not production-ready."""
    
        def do_GET(self) -> None:
            self._respond(
                dispatch("GET", self.path),
                send_body=True,
            )
    
        def do_HEAD(self) -> None:
            self._respond(
                dispatch("HEAD", self.path),
                send_body=False,
            )
    
        def do_POST(self) -> None:
            self._respond(
                dispatch("POST", self.path),
                send_body=True,
            )
    
        def do_PUT(self) -> None:
            self._respond(
                dispatch("PUT", self.path),
                send_body=True,
            )
    
        def do_PATCH(self) -> None:
            self._respond(
                dispatch("PATCH", self.path),
                send_body=True,
            )
    
        def do_DELETE(self) -> None:
            self._respond(
                dispatch("DELETE", self.path),
                send_body=True,
            )
    
        def do_OPTIONS(self) -> None:
            self._respond(
                dispatch("OPTIONS", self.path),
                send_body=True,
            )
    
        def _respond(
            self,
            reply: Reply,
            *,
            send_body: bool,
        ) -> None:
            payload = reply.encoded()
    
            self.send_response(reply.status)
    
            self.send_header(
                "Content-Type",
                reply.content_type + "; charset=utf-8",
            )
    
            self.send_header(
                "Content-Length",
                str(len(payload)),
            )
    
            self.send_header(
                "Cache-Control",
                "no-store",
            )
    
            if reply.allow is not None:
                self.send_header("Allow", reply.allow)
    
            self.end_headers()
    
            if send_body:
                self.wfile.write(payload)
    
        def log_message(
            self,
            format: str,
            *args: object,
        ) -> None:
            pass
    
    
    def demo() -> None:
        cases = (
            ("baseline", "v1"),
            ("expanded", "v1"),
            ("expanded", "v2"),
        )
    
        for release, version in cases:
            response = dispatch(
                "GET",
                f"/{version}/books/bk-001",
                release,
            )
    
            print(
                release,
                version,
                response.status,
                json.dumps(
                    response.body,
                    ensure_ascii=False,
                ),
            )
    
        old = dispatch(
            "GET",
            "/v1/books/bk-001",
            "baseline",
        )
    
        new = dispatch(
            "GET",
            "/v1/books/bk-001",
            "expanded",
        )
    
        print(
            "TOLERANT_BASELINE:",
            old_tolerant_client(old),
        )
    
        print(
            "TOLERANT_EXPANDED:",
            old_tolerant_client(new),
        )
    
        try:
            old_strict_client(new)
        except ValueError as exc:
            print("STRICT_BREAKS:", str(exc))
    
        coexist = all(
            dispatch(
                "GET",
                f"/{version}/books/bk-001",
            ).status == 200
            for version in ("v1", "v2")
        )
    
        print("V1_V2_COEXIST:", coexist)
    
        head_ok = (
            dispatch(
                "HEAD",
                "/v1/books/bk-001",
            ).status == 200
        )
    
        print("HEAD_EQUALS_GET_STATUS:", head_ok)
        print("NOTE: Contract simulation, not a real migration")
    
    
    def main() -> None:
        if len(sys.argv) == 1 or sys.argv[1:] == ["--demo"]:
            demo()
    
        elif sys.argv[1:] == ["--serve"]:
            with ThreadingHTTPServer(
                ("127.0.0.1", 0),
                LocalHandler,
            ) as server:
    
                port = server.server_address[1]
    
                print(
                    f"LOCAL_ONLY http://127.0.0.1:{port}",
                    flush=True,
                )
    
                try:
                    server.serve_forever()
                except KeyboardInterrupt:
                    pass
    
        else:
            raise SystemExit(
                "Usage: python "
                "L5_016_api_contract_lab_v2.py "
                "[--demo|--serve]"
            )
    
    
    if __name__ == "__main__":
        main()

    ──────────────────
    ■実装を六つの部分に分けて理解する

    第1部分|内部データ

    BOOKSには、架空の図書情報が入っています。

    内部データとしてauthorとlanguageを保持していますが、外部へ返す情報はAPIのバージョンによって変わります。

    第2部分|表現の変換

    represent()が、内部データからv1またはv2の応答を生成します。

    第3部分|要求の判定

    dispatch()が、メソッド、URL、パラメータ、対象の本を確認します。

    第4部分|旧クライアントの再現

    old_tolerant_client()とold_strict_client()で、追加項目への対応が異なる二種類の旧クライアントを再現します。

    第5部分|HTTPサーバー

    LocalHandlerが、GET、HEAD、対応していないメソッドへの応答を実行します。

    第6部分|実験モード

    --demoで互換性の比較を実行し、--serveでローカルHTTPサーバーを起動します。

    「APIの内部データと、外から見える契約を分けているんだね」

    MAI:「はい。内部構造を変更しても、必要な外部契約を維持しやすくするためです」

    ──────────────────
    ■実行方法

    プログラムをUTF-8で保存します。

    Windowsの場合:

    py L5_016_api_contract_lab_v2.py --demo

    macOS・Linuxの場合:

    python3 L5_016_api_contract_lab_v2.py --demo

    このモードではHTTPサーバーを起動せず、プログラム内部で契約の変更前後を比較します。

    ローカルHTTPを試す場合は、

    python3 L5_016_api_contract_lab_v2.py --serve

    を実行します。

    Windowsでは、必要に応じてpython3をpyへ置き換えます。

    起動時には、127.0.0.1に割り当てられたポート番号が表示されます。

    外部のWebサービスへの通信は必要ありません。

    ──────────────────
    ■実行結果|変更前と変更後

    実際に取得した結果は、次のとおりです。

    baseline v1 200 {"id": "bk-001", "title": "星の手帖", "author": "青木遥"}
    
    expanded v1 200 {"id": "bk-001", "title": "星の手帖", "author": "青木遥", "language": "ja"}
    
    expanded v2 200 {"id": "bk-001", "title": "星の手帖", "contributors": [{"name": "青木遥", "role": "author"}], "language": "ja"}
    
    TOLERANT_BASELINE: 星の手帖 / 青木遥
    TOLERANT_EXPANDED: 星の手帖 / 青木遥
    STRICT_BREAKS: Unexpected response shape
    V1_V2_COEXIST: True
    HEAD_EQUALS_GET_STATUS: True
    NOTE: Contract simulation, not a real migration

    「ねえAI、追加項目を無視する旧クライアントは、変更後も動いたんだね」

    MAI:「はい」

    「でも、厳密に三項目だけを要求するクライアントは失敗した」

    MAI:「その通りです」

    「そして、v1とv2の両方を取得できた」

    MAI:「はい。ただし、旧クライアントが自動的にv2へ対応したという意味ではありません」

    ──────────────────
    ■契約テストとは何か?

    契約テスト(Contract Testing)は、APIの提供側と利用側の間で、約束した条件が守られているか確認する試験です。

    例えば、旧クライアントが必須としている三項目を検証します。

    result = dispatch(
        "GET",
        "/v1/books/bk-001",
        "expanded",
    )
    
    assert result.status == 200
    
    for key in ("id", "title", "author"):
        assert isinstance(result.body[key], str)

    「これで、v1の必須項目が残っているか確認できるんだね」

    MAI:「はい」

    ただし、これだけでは、未知の追加項目を旧クライアントが許容できるかは確認できません。

    そのため、旧クライアントの実際の読み取り処理を模擬したテストも用意します。

    Schema Test ≠ Consumer Behavior Test.

    スキーマの検査と、クライアントの動作検査は別です。

    ──────────────────
    ■今回の108件の自動テスト

    旧版で使用した61件のテストを基礎とし、改訂版では47件を追加しました。

    検証対象は、主に次の領域です。

    契約の維持

    v1の必須項目と値が、変更後も維持されるか。

    旧クライアントの動作

    追加許容型と厳密固定型で、結果が異なるか。

    v1・v2の併存

    新しい構造が旧版へ強制適用されないか。

    HTTPメソッド

    GETとHEADが適切に動作するか。

    HEADの応答

    実際のHTTP通信で、本文が送られないか。

    405のAllowヘッダー

    対応メソッドがGET、HEADとして示されるか。

    未知のURL

    存在しないパスと、許可されないメソッドを区別できるか。

    クエリ検証

    不正なlimit、重複パラメータ、空欄、文字形式を区別できるか。

    エラー形式

    Problem Detailsのstatusと、実際のHTTPステータスが対応するか。

    内部データ

    GETやHEADの処理で、元のデータが変更されないか。

    ローカルHTTP

    127.0.0.1上で実際に要求と応答を確認できるか。

    ──────────────────
    ■自動テストの実行結果

    テストファイル:

    L5_016_api_contract_tests_v2.py

    実行コマンド:

    python3 L5_016_api_contract_tests_v2.py

    Python 3.13.5での実行結果は、次のとおりです。

    ----------------------------------------------------------------------
    Ran 108 tests in 1.044s
    
    OK

    108件中108件成功。

    また、旧版のテストも改めて実行しました。

    ----------------------------------------------------------------------
    Ran 61 tests in 0.549s
    
    OK

    この結果から、旧版の61件の検証が成功し、改訂版の108件でも期待した動作を確認できました。

    ただし、テストに成功したことと、すべての互換性が証明されたことは別です。

    Tests Passed ≠ Universal Compatibility.

    テストの成功は、すべての利用者に対する互換性を保証しません。

    ──────────────────
    ■OpenAPI契約を精査する

    APIの契約を構造的に記述する方法として、OpenAPIがあります。

    今回の改訂では、OpenAPI 3.1形式の仕様書を更新しました。

    対象は、

    /v1/books

    /v1/books/{book_id}

    /v2/books

    /v2/books/{book_id}

    の4パスです。

    各パスについてGETとHEADを記述し、計8操作を対象にしました。

    さらに、limitの書式、405のAllowヘッダー、countの意味を整理しました。

    ここでのcountは、今回の応答に含まれる件数を意味します。

    登録されているすべての本の総数という意味ではありません。

    例えば、三冊が登録されている今回の教材で、

    GET /v1/books?limit=1

    を要求した場合、countは1です。

    登録数が3だからといって、countが3になるわけではありません。

    ──────────────────
    ■contributorsの役割は将来変更できる?

    Renaは、v2の構造をもう一度確認した。

    「ねえAI、contributorsにしても、roleがauthorしか認められなかったら、翻訳者を追加できないよね?」

    MAI:「その通りです」

    前稿のOpenAPI記述例では、roleの許容値がauthorだけに限定されていました。

    しかし、今回の目的は、著者以外の役割も表現できる構造を考えることです。

    そこで、改訂版ではroleを文字列として記述し、author、editor、translatorなどを既知の例として扱います。

    ただし、クライアント側で未知の役割が来る可能性をどう扱うかも決める必要があります。

    Unknown Enum Value ≠ Invalid Real-World Data.

    未知の列挙値が現れたことだけで、そのデータが現実に存在しないと判断してはいけません。

    一方、roleを自由な文字列にしたからといって、入力内容が何でも意味的に正しいわけでもありません。

    実際に新しい役割を登録する場合には、意味の定義、保存方法、表示方法、旧版への変換方法などを設計する必要があります。

    今回の試作では、roleとしてauthorだけを返しています。

    複数の関係者を登録・編集する機能は未実装です。

    ──────────────────
    ■OpenAPIの検証結果

    今回、改訂したOpenAPIのYAMLファイルを解析しました。

    また、参照を含むJSON Schemaを使って、v1・v2の一覧および詳細応答を検証しました。

    結果:

    YAML: parsed
    
    OpenAPI version: 3.1.0
    
    Documented paths: 4
    
    GET/HEAD operations: 8
    
    Referenced JSON Schema sample responses:
    4 passed
    
    Formal full-OpenAPI specification validation:
    NOT RUN

    4種類のサンプル応答について、設定したJSON Schemaとの一致を確認しました。

    ただし、これはOpenAPI仕様全体の完全な適合性検証ではありません。

    専用のOpenAPIバリデーターによる全面検査や、外部SDKを生成しての互換性検証は未実施です。

    ──────────────────
    ■六つのケースで設計判断を行う

    ケース1|v1の必須項目を維持する

    既存項目を維持し、値の意味も変えない。

    判定|今回の契約テストでは成立。

    注意|実在クライアントの暗黙の前提までは未確認。

    ケース2|languageを追加する

    v1の三項目を維持したまま、任意項目を追加する。

    判定|追加許容型クライアントでは成功。

    厳密固定型では失敗。

    注意|失敗したことだけでは、どちらが契約違反か確定しない。

    ケース3|authorを削除する

    旧クライアントが必要とする項目を削除する。

    判定|今回の旧クライアントでは破壊的変更。

    対応|旧契約の維持、または明示的な移行が必要。

    ケース4|v2を新設する

    contributorsを持つ新しい契約を提供する。

    判定|v1とv2の併存を確認。

    注意|旧クライアントの自動移行は未実施。

    ケース5|存在しないURLや不正なHTTP要求

    404、405、400などを区別する。

    判定|今回の実装とローカルHTTP試験で確認。

    注意|インターネット公開時の安全性は未検証。

    ケース6|v1を停止する

    v2の実装とテストが成功した。

    しかし、実在する利用者の移行状況は不明。

    判定|HOLD。

    理由|v2の完成だけでは、v1を停止してよい条件が成立したとはいえない。

    ──────────────────
    ■v1を停止してよい条件は何か?

    「ねえAI、v2が完成したら、v1はもう消していいの?」

    MAI:「いいえ。移行の成立条件を確認する必要があります」

    例えば、

    ・v1を使う利用者が残っているか。
    ・残っている利用者がどの機能を必要としているか。
    ・移行案内が届いているか。
    ・v2で必要な機能を利用できるか。
    ・移行後に新しい障害が起きていないか。
    ・契約上の告知期間を満たしているか。
    ・停止後の復旧方法があるか。

    などが考えられます。

    「新版を公開しただけじゃ、移行完了とは言えないんだね」

    MAI:「はい」

    New Version Released ≠ Migration Completed.

    新版公開と移行完了は別です。

    また、

    Low Usage ≠ Safe Retirement.

    旧版の利用件数が少なくなっただけで、安全に停止できるとは限りません。

    ──────────────────
    ■旧版の維持にも費用がかかる

    Renaは考えた。

    「じゃあ、v1をずっと残しておけば安心なんじゃない?」

    MAI:「旧版を維持することにも負担があります」

    例えば、複数バージョンの保守、セキュリティ修正、テスト、障害調査、ドキュメント管理などです。

    旧版を長期間残すことで、新しい機能の設計が制約を受ける場合もあります。

    一方で、旧版を急に停止すると、利用者がサービスを使えなくなる可能性があります。

    そのため、必要なのは単純な永続維持でも、即時停止でもありません。

    保守負担と利用者への影響を、証拠に基づいて比較することです。

    ──────────────────
    ■変更を公開するための設計レビュー

    実際のAPI変更では、少なくとも次の状態を区別します。

    DESIGNED|設計済み

    新しい契約と変更理由が整理されている。

    IMPLEMENTED|実装済み

    新しいコードが作成されている。

    VERIFIED|限定検証済み

    設定したテスト条件で期待結果が確認されている。

    COMPATIBILITY REVIEW|互換性評価中

    既存利用者や旧契約への影響を確認している。

    MIGRATION READY|移行準備済み

    移行手順、通知、必要な運用条件が用意されている。

    DEPLOYMENT APPROVED|公開判断済み

    責任を持つ人間または組織が、適用を承認している。

    これらは、今回の教材で設計判断を整理するための状態名です。

    特定の標準規格で必須と定められた状態名ではありません。

    「設計が終わったことと、テストが成功したことと、公開していいことは違うんだね」

    MAI:「はい」

    Implementation ≠ Verification ≠ Deployment Approval.

    実装、検証、公開承認は、それぞれ異なる行為です。

    ──────────────────
    ■今回の精査で修正した七つの重要点

    修正1|HEADへの対応

    前稿はHTTPサーバーでHEADを明示的に実装していませんでした。

    改訂版ではHEADに対応し、本文を送らない動作を確認しました。

    修正2|405のAllowヘッダー

    GETとHEADの両方を許可する設定に更新しました。

    修正3|存在しないURLの扱い

    存在しないパスへの要求と、既知のリソースに許可されないメソッドを区別しました。

    修正4|クエリパラメータ

    空欄、重複、不正な文字列などをより厳密に判定するようにしました。

    修正5|OpenAPIと実装の整合

    limitの入力書式を、仕様書でも明示しました。

    修正6|contributorsの拡張性

    roleをauthorだけに限定せず、未知の役割値への対応が必要であることを明確にしました。

    修正7|互換性の判断

    実際のクライアントの失敗と、提供側の契約違反を区別しました。

    これらは、旧版の機能をすべて否定する修正ではありません。

    旧版は61件のテストに合格していました。

    今回は、契約の精度、HTTPの整合性、検証範囲の明示を強化しました。

    ──────────────────
    ■今回の実装で確認できたこと

    確認1|旧版の回帰試験

    61件の旧版テストが成功しました。

    確認2|改訂版の自動テスト

    108件が成功しました。

    確認3|v1必須項目の維持

    変更後もid、title、authorが維持されました。

    確認4|追加項目への対応差

    追加許容型クライアントは動作し、厳密固定型は失敗しました。

    確認5|v1とv2の併存

    両方のAPIを取得できました。

    確認6|HEAD

    ローカルHTTP通信で、HEADの本文が送信されないことを確認しました。

    確認7|405とAllow

    許可されないメソッドに対する応答を確認しました。

    確認8|URLとクエリ

    不正なパラメータ、重複、不正な形式を検査しました。

    確認9|エラー応答

    400、404、405などの応答と、Problem Detailsの内容を確認しました。

    確認10|内部データの保持

    今回のGET・HEAD処理が元データを変更しないことを確認しました。

    確認11|OpenAPIの部分検証

    YAMLを解析し、4種類のサンプル応答についてJSON Schemaとの一致を確認しました。

    ──────────────────
    ■検証していないこと

    限界1|実在クライアントの互換性

    実際に利用されているスマートフォンアプリやSDKは検査していません。

    限界2|本番APIの変更

    実際に運用されているAPIを更新していません。

    限界3|複数の関係者の登録

    v2はcontributors配列を返しますが、複数の著者・編集者・翻訳者の登録処理は実装していません。

    限界4|データベース移行

    永続保存や、旧データから新データへの移行は実施していません。

    限界5|認証・認可

    利用者認証やアクセス権限の検証を実装していません。

    限界6|TLS・HTTPS運用

    ローカルHTTPでの試験に限定しています。

    限界7|高負荷試験

    大量アクセスに対する性能や安定性を測定していません。

    限界8|完全なHTTPサーバー機能

    すべてのHTTP機能や異常なネットワーク条件を検証していません。

    限界9|完全なOpenAPI適合性

    専用バリデーターによるOpenAPI仕様全体の検証は未実施です。

    限界10|実際の移行率

    旧版から新版へ移行した利用者数は測定していません。

    限界11|旧版停止の安全性

    実在する利用者への影響や、停止後の復旧可能性は未確認です。

    限界12|すべての互換性問題

    108件のテストでは、実在システムのすべての暗黙の契約を網羅できません。

    ──────────────────
    ■Renaが理解した変更しやすいAPIの本質

    夕方。Renaは、最初に作った図書情報のデータ形式を見つめていた。

    新しい機能を追加することは、難しいことではないと思っていた。

    authorという項目を削除する。

    contributorsという配列を追加する。

    新しい形式を返すようにコードを書き換える。

    それだけで、機能は増やせる。

    しかし、すでにそのAPIを利用しているアプリが存在する。

    そのアプリは、以前の契約に従って作られている。

    新しい機能が正常に動いても、以前の利用者が使えなくなる場合がある。

    「ねえAI、最初は変更しやすいAPIって、プログラムを直しやすいことだと思っていたよ」

    MAI:「はい」

    「でも、本当に大切なのは、どこを変更してもよくて、どこは以前の約束を守らないといけないかを分けることなんだね」

    MAI:「その通りです」

    「それに、旧クライアントが壊れたからといって、すぐに提供側が悪いと決めることもできない」

    MAI:「はい。実際に何が契約されていたかを確認する必要があります」

    「そして、契約テストに成功しても、現実の利用者が全員大丈夫とは限らない」

    MAI:「その通りです」

    「だから、実装、検証、移行、公開判断を分けるんだね」

    MAI:「はい」

    Renaはノートに、今日の結論を書いた。

    変更しやすいAPI設計とは、単に内部のコードを書き換えやすくすることではなく、APIが外部へ提供している契約を明確にし、変更による影響を把握・検証・管理できる構造を作ることである。API契約には、要求方法、応答形式、必須項目、データ型、意味、エラー、認証、運用条件などが含まれる。追加的変更は互換性を維持しやすいが、未知の項目を許容しない旧クライアントでは失敗する場合がある。ただし、その失敗が提供側の契約違反を意味するかは、実際の契約に依存する。必須項目の削除、型や意味の変更、新しい必須入力の追加などは、破壊的変更となる可能性がある。そのため、必要に応じてv1とv2を分離し、旧契約を維持しながら移行する方法が考えられる。また、OpenAPIによる契約の文書化、契約テスト、回帰テスト、実際のHTTP通信試験などによって、変更の影響を確認できる。ただし、テスト成功は実在するすべての利用者との互換性を保証しない。新版の実装、検証、公開、利用者の移行、旧版停止は、それぞれ独立した確認事項である。変更しやすいAPIとは、変更の自由度を高めるだけでなく、変更しなければならないものと、維持すべき約束を識別し、その影響を管理できるように設計されたAPIである。

    「今まで使っていた人との約束も、プログラムの設計に含まれているんだね」

    MAIの青いデジタルの目が、静かに光った。

    MAI:「はい。変更しやすいAPIとは、変更そのものを簡単にするだけでなく、変更しても何が守られるかを説明し、確認できるAPIです」

    ──────────────────
    ■今回の学習まとめ

    1|API
    ソフトウェア同士が機能や情報を利用するための接点。

    2|API契約
    要求、応答、意味、エラー、運用などの取り決め。

    3|後方互換性
    旧クライアントが以前の契約に基づいて利用を続けられる性質。

    4|破壊的変更
    以前の契約や利用方法との互換性を失わせる変更。

    5|追加的変更
    既存の項目などを維持しながら、新しい要素を追加する変更。

    6|スキーマ
    データの項目、型、必須条件などを定義した構造。

    7|意味の互換性
    値の形式だけでなく、単位や解釈が維持されること。

    8|APIバージョニング
    異なるAPI契約を管理するためにバージョンを分ける方法。

    9|GET
    情報の取得を目的とするHTTPメソッド。

    10|HEAD
    GETに対応する応答のメタデータを取得し、HTTP本文は転送しないメソッド。

    11|HTTP 405
    対象リソースで要求されたメソッドが許可されないことを示すステータス。

    12|Allowヘッダー
    対象リソースで許可されるHTTPメソッドを示すヘッダー。

    13|Problem Details
    HTTP APIのエラー情報を構造化して表現する仕組み。

    14|OpenAPI
    HTTP APIのインターフェースを記述するための仕様。

    15|契約テスト
    APIが取り決めた条件を守っているか確認するテスト。

    16|回帰テスト
    変更によって以前の機能が壊れていないか確認するテスト。

    17|Consumer-Driven Contract
    利用側の期待を契約検証へ反映する考え方。

    18|Schema Evolution
    データ構造を変更・発展させること。

    19|Deprecation
    機能やバージョンを非推奨とすること。

    20|Migration
    旧契約から新契約へ移行すること。

    21|互換性の検証境界
    どの契約、どのクライアント、どの条件まで検証したかを明確にすること。

    22|公開判断
    技術的な完成とは別に、現実の変更を適用してよいか判断すること。

    最も重要な理解

    APIの変更容易性は、内部実装を修正しやすいことだけでは成立しない。外部との契約を明確にし、旧クライアントへの影響を確認し、新版への移行と公開判断まで分けて設計する必要がある。

    ──────────────────
    ■理解問題|5問

    問題1|後方互換性

    後方互換性とは何か?

    A|新しいAPIは必ず古いAPIより速いこと。
    B|旧クライアントが以前の契約に基づいて利用を続けられること。
    C|バージョン番号を大きくすること。

    問題2|フィールド追加

    v1の応答にlanguageを追加した場合、正しい説明はどれ?

    A|すべての旧クライアントで必ず安全。
    B|すべての旧クライアントが必ず失敗。
    C|契約とクライアントの実装により影響が異なる。

    問題3|破壊的変更

    authorを削除してcontributorsへ変更した場合は?

    A|旧クライアントがauthorを必要としていれば失敗する可能性がある。
    B|名前を変えただけなので必ず安全。
    C|JSONは自動的に旧形式へ変換される。

    問題4|HTTP HEAD

    HEADの動作について適切なのは?

    A|GETと同じように必ず本文を送る。
    B|GETに対応するステータスや表現メタデータを返し、HTTP本文は送らない。
    C|サーバーのデータを必ず削除する。

    問題5|旧版停止

    v2のテストが成功した場合、v1を停止してよいか?

    A|直ちに停止してよい。
    B|v2の公開と同時に全利用者が移行したとみなす。
    C|旧版利用者や移行状況、停止の影響を確認する必要がある。

    解答と解説

    問題1|B。後方互換性は、旧契約に従う利用者の継続利用に関する性質です。

    問題2|C。追加項目が許容されるかどうかは、契約と実装によります。

    問題3|A。旧クライアントが参照する項目を削除すると、動作に影響する可能性があります。

    問題4|B。HEADはGETに対応するメタデータを取得するために使用できますが、本文は転送しません。

    問題5|C。新版の完成と、旧版の安全な停止は別です。

    ──────────────────
    ■専門設計・検証課題

    課題1|互換性を分類する

    目的|変更がどの契約へ影響するか判断する。

    次の変更について、互換性への影響と必要な検証を整理します。

    ① languageを追加する。
    ② authorを削除する。
    ③ titleを文字列から配列へ変更する。
    ④ 新しい必須パラメータを追加する。
    ⑤ priceの意味を税抜から税込へ変更する。
    ⑥ 新しいroleを追加する。

    完成条件|どのクライアントが、どのような理由で失敗する可能性があるか説明できること。

    課題2|契約テストを追加する

    目的|旧クライアントが必要とする条件を明確にする。

    手順|
    ① v1の必須項目を確認する。
    ② 追加許容型クライアントの契約を定義する。
    ③ 厳密固定型クライアントの契約を定義する。
    ④ language追加後に両方をテストする。
    ⑤ 失敗と契約違反を分けて記録する。

    完成条件|互換性を「動いた・動かない」だけで判断せず、契約との関係を説明できること。

    課題3|HEADを検証する

    目的|HTTPメソッドの契約を理解する。

    手順|
    ① GETで本の情報を取得する。
    ② HEADで同じ対象を要求する。
    ③ HTTPステータスを比較する。
    ④ Content-TypeとContent-Lengthを確認する。
    ⑤ HEADで本文が送信されないことを確認する。

    完成条件|GETとHEADの役割の違いを説明できること。

    課題4|新しい関係者の役割を設計する

    目的|スキーマの拡張性と実装上の制約を理解する。

    設定|contributorsへ翻訳者や編集者を追加したい。

    考えること|
    ① roleをどのように表すか。
    ② 未知のroleをクライアントがどう扱うか。
    ③ 複数のauthorをどう表現するか。
    ④ v1のauthorへ戻す場合に情報が失われないか。
    ⑤ 新しいデータをどこに保存するか。

    完成条件|配列を追加しただけでは複数関係者の管理が完成しないことを説明できること。

    課題5|v1からv2への移行計画

    目的|新版公開と移行完了を区別する。

    検討項目|
    ① 現在の利用者を把握する。
    ② 必要な旧契約を整理する。
    ③ v2の移行手順を作成する。
    ④ 契約テストを実行する。
    ⑤ 移行後の障害を観測する。
    ⑥ 旧版停止の条件を明確にする。
    ⑦ 停止判断を行う責任者を定める。

    完成条件|新版の完成だけを根拠に、旧版の停止を決定しない計画を作れること。

    ──────────────────
    ■参考資料

    Google|AIP-180・Backwards Compatibility
    https://google.aip.dev/180

    Google Cloud|API Design Guide
    https://docs.cloud.google.com/apis/design

    Microsoft|Web API Design Best Practices
    https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design

    OpenAPI Initiative|OpenAPI Specification v3.1
    https://spec.openapis.org/oas/v3.1

    IETF|RFC 9110・HTTP Semantics
    https://www.rfc-editor.org/rfc/rfc9110.html

    IETF|RFC 9457・Problem Details for HTTP APIs
    https://www.rfc-editor.org/rfc/rfc9457.html

    Python Software Foundation|http.server
    https://docs.python.org/3/library/http.server.html

    Python Software Foundation|urllib.parse
    https://docs.python.org/3/library/urllib.parse.html

    Python Software Foundation|unittest
    https://docs.python.org/3/library/unittest.html

    ※APIの後方互換性と変更の影響については、Googleの公開指針を参照しています。
    ※HTTPメソッドとステータスについてはRFC 9110、エラー表現についてはRFC 9457を参照しています。
    ※APIの契約記述についてはOpenAPI 3.1を参照しています。
    ※本文の図書情報サービス、人物、会話、開発場面は教育目的の創作です。

    ──────────────────
    ■制作・専門設計・実装検証について

    本作品は「AI実装型座談会|RenaとMAIのデジタル探検編」の独立した教育記事です。

    制作規格|RM-ACF v1.2
    学習区分|LEVEL 5・ENGINEER/専門設計編
    対象テーマ|L5-016
    正式題名|AI、変更しやすいAPI設計とは?
    記事版|v2.0・内容精査/完全改訂版
    制作日|2026年11月20日

    構成・本文・会話・API設計・Pythonコード・契約検証・理解問題・専門課題生成|AI
    テーマ・制作方針・採用・公開判断|人間

    RenaとMAIは架空の登場人物です。

    今回の実装では、架空の図書情報を提供するAPIを作成しました。

    v1の必須項目はid、title、authorです。

    追加的変更の実験では、これらの項目を維持したままlanguageを追加しました。

    破壊的変更の例として、authorをcontributors配列へ置き換えたv2を別に提供しました。

    なお、v2で返す関係者は今回の試作ではauthor一人のみです。

    複数の著者・編集者・翻訳者を登録・編集する機能は実装していません。

    また、未知の追加項目を許容する旧クライアントと、応答項目を厳密に固定する旧クライアントを用意しました。

    それぞれについて変更前後の動作を確認しました。

    さらに、HTTPのGET、HEAD、405のAllowヘッダー、404との区別、クエリパラメータの書式検証などを精査しました。

    実装環境はPython 3.13.5です。

    旧版の61件の自動テストを再実行し、すべて成功しました。

    改訂版では47件のテストを追加し、計108件を実行しました。

    自動テスト108件は、すべて成功しました。

    また、127.0.0.1上でのHTTP試験を実施し、HEADがHTTP本文を送らないことなどを確認しました。

    OpenAPI 3.1形式の仕様書を更新し、4パス・GET/HEAD計8操作を記述しました。

    仕様書のYAML解析と、4種類のサンプル応答に対するJSON Schema検証は成功しました。

    ただし、専用のOpenAPI適合性検査ツールによる、仕様全体の完全な検証は実施していません。

    今回の実装は、教育用の固定データとローカルHTTPサーバーによるものです。

    実際の図書情報システムを変更したものではありません。

    実在するクライアントの互換性、本番環境への公開、認証・認可、TLS、永続保存、データベース移行、大規模負荷、実際の旧版停止などは未検証です。

    したがって、今回の成功結果を、実在するすべての利用者の互換性や、本番運用の安全性として扱うことはできません。

    APIの内部変更、契約の互換性、クライアントの動作、テストの成功、新版の公開、利用者の移行、旧版停止の判断は、それぞれ異なる確認事項です。

    本作品の生成、実装、検証、確認、採用、保存、共有、公開、現実の運用変更は、それぞれ別の行為です。

    「知らなくても始められる。どこまでも深く学べる。」

    #AI #AI座談会 #I2OS #Rena #MAI #デジタル探検編 #API設計 #API互換性 #後方互換性 #BreakingChange #OpenAPI #RESTAPI #契約テスト #回帰テスト #SchemaEvolution #バージョン管理 #Python #HTTP #ソフトウェア設計 #システム開発 #AI教育

     
     

    ANDOM

     
     
    I2OS|人間を超えるAI能力を、社会が理解・検証・許可・運用・修復できる形へ研究・構造化。「AIは人間を超えるか」ではなく「超えた能力をどう現実へ通すか」。Beyond AGI|全投稿AI生成|Xで広域DB構築・記録検証中|20:00〜24:00の趣味

    あなたへのおすすめ