openapi-glossary

OpenAPI 用語集

出典：https://github.com/apisyouwonthate/api-glossary

教育資料やツールなどのコンテンツを作成する際に混乱を避けるには、共通の語彙を持つことが重要です。OpenAPI コミュニティでは、多くの人がさまざまなものをさまざまな名前で呼んでいるので、ここで用語の統一を試みます。

API

一般的な定義である「Application Program Interface」は、さまざまな種類のインターフェースを指し、多くの意味を持ちます。OpenAPI が対象とするのは、特に HTTP ベースの API です。一般的には、REST、REST に近いもの、および多くの汎用的な RPC が該当します。

API ファースト

API が普及し始めた頃、多くの企業がマーケティング目的で API を次々と公開し始めました。こうした API は、一般的にあまり実用的ではなく、性能も低いことが多く、使いにくいものでした。

「API ファースト」とは、チームがまず API を構築し、自分たちが使いたいと思えるものにすることで、使いやすさやパフォーマンスなどの問題を解決し、顧客により良い体験を提供することを目指す考え方です。

API の記述

別名：「API 定義」または「API コントラクト」。

API の記述とは、API に関するメタデータであり、どのようなエンドポイント、リソース、HTTP メソッド、ヘッダー、クエリパラメーターなどが存在するかを説明します。

記述は特定の「API 記述形式」（例：OpenAPI、JSON Schema、RAML、WSDL など）で作成され、通常は「API 記述ドキュメント」（例：openapi.yaml、schemas/payment.json）にまとめられます。ただし、作成者が代わりにアノテーションを使う場合もあります。

API 設計

API 記述、または API 記述を生成・エクスポートするツールを用いて API を計画することです。コーディングを始める前に行う場合は「API 設計ファースト」と呼ばれます。これは概念上、API ファーストとは異なりますが、両立しないわけではありません。

API 設計ファーストとコードファーストの比較の詳細をご覧ください。

API 仕様

以前は、API 仕様という用語は、多くの主要なツールベンダーがAPI 記述ドキュメントと呼ぶものを表す、数ある用語のひとつでした。ユーザーが自分の API を記述するために作成するファイルを指していました。

100 人に尋ねれば 100 通りの答えが返ってくるでしょうが、API 仕様は API 開発に関わるさまざまな仕様をまとめた包括的な用語であり、その中にさらに具体的な分類が存在する、という認識が形成されつつあります。

JSON-API、HAL、Siren などのメッセージ形式には、それぞれ仕様があります。 JSON、YAML などのデータ形式にも、それぞれ仕様があります。 SPDY、HTTP/2、HTTP/3 などの転送プロトコルにも、それぞれ仕様があります。 OAuth 2、OpenID などの認証方式にも、それぞれ仕様があります。

このように API 仕様にはさまざまな種類があるため、意味の混同を避けるには、この用語を使わず、より具体的な分類のいずれかを使うのが最善です。自分の openapi.yaml について話すのであれば、「記述ドキュメント」と呼ぶとよいでしょう。

バンドル

別名：「外部インライン化」。

バンドルでは、別のファイルや URL にある外部の $refs を取り込み、components オブジェクトにまとめます。

これは、単一の OpenAPI ファイルを作成するために行います。特に、外部ファイルの解決に対応していないツールでも共有しやすくなります。ツールが $ref 自体に対応していない場合は、バンドルの代わりにデリファレンスが必要です。

コールバック

多くのプログラミング言語にはコールバックという概念があります。これは、別の関数が完了した後に実行される関数を、別の関数に引数として渡すものです。API にもまったく同じ概念があり、処理が完了したときに通知を受け取るための URL を渡せます。

これは通常 Webhook を介して行われるため、Callabck よりも Webhook という用語のほうが一般的ですが、OpenAPI では特にコールバックについて説明しています。

たとえば、API が POST /subscribe 操作を提供し、リクエストボディにコールバック URL を指定することを想定しているとします。

POST /subscribe
Host: my.example.com
Content-Type: application/json
{
  "callbackUrl": "https://myserver.com/send/callback/here"
}

その URL に Webhook が送信されます。

OpenAPI のコールバックについて詳しくは、Swagger Docs: Callbacks をご覧ください。

コード生成

コントラクトテスト

API が仕様どおりにデータを受け付け、出力していることを確認する方法はさまざまです。OpenAPI に関連してコントラクトテストという用語を耳にする場合、一般的にはプロデューサー側のコントラクトテストを指します。これは、API 開発チーム（または近くにいるテスト／QA チーム）が、API の記述を取得し、実際のデータと比較するテストスイートを実装することを意味します。

概念的には、コントラクトテストはデータ検証と同じですが、ライフサイクルの異なる段階で、異なる目的のために行われます。内部では同じツールを使用できます。

クライアント側のコントラクトテストもあります。クライアントのテストスイートにコントラクトを記述し、API を呼び出して一致するかどうかを確認します。

コンバーター

OpenAPI の記述を API Blueprint、HAR、RAML などの別の記述形式に変換したり、その逆を行ったりするツール群です。HTML に変換できるものもあり、通常はリファレンスドキュメントの作成に使用されます。

データインスタンス

データ検証

検証にはさまざまな種類があるため、単に「検証」と呼ばれることもよくあります。データ検証とは、実際のデータ（ボディを含む HTTP メッセージ全体の場合も、ボディだけの場合もあります）を取得し、API の記述と比較することです。

これは、コントラクトテスト、ゲートウェイ検証、サーバー側検証などに利用されます。

参照解決

別名：「参照の解決」、「内部インライン化」、「トランスクルージョン」。

すべての $ref がその値に置き換えられ、コピー＆ペーストしたような状態になります。ファイル／オブジェクト表現には $ref が残りません。同じモデルを参照する操作が 10 個ある場合、それぞれに 10 個の異なるモデルが配置されます。

記述の検証

別名：「スキーマ検証」。

データ検証とは大きく異なる種類の検証です。記述の検証では、記述が OpenAPI 仕様自体に照らして正しいことを確認します。

バリデーターがドキュメントの有効性確認にとどまらず、カスタムルール、設計上の見解、スタイルなどを対象とする場合、「リンティング」という用語が使われます。

OpenAPI.Tools で記述バリデーターの一覧を確認できます。

ドキュメント

OpenAPI の世界でドキュメントという場合、最も一般的にはリファレンスドキュメントを意味しますが、優れた API ドキュメントに必要なのはそれだけではありません。最適な開発者体験を提供するため、ガイド、チュートリアル、その他の手順を説明するコンテンツがリファレンスドキュメントと組み合わされることがよくあります。このようなコンテンツに「API トークンの登録」機能などを組み合わせたものは、デベロッパーポータルと呼ばれることがよくあります。

ゲートウェイ検証

API ゲートウェイでデータ検証を行うことをゲートウェイ検証と呼びます。無効なリクエストがアプリケーションのリソースを消費するのを防ぎます。AWS、Tyk、Express Gateway などは、OpenAPI または JSON Schema によるゲートウェイ検証をある程度サポートしています。

リンク

コンピューティングや API の概念におけるリンクには多くの意味がありますが、OpenAPI にはレスポンスに対する設計時のリンク候補を表す Link Object があります。

レスポンスごとに次に利用できるアクションのヒントを示すことで、API ドキュメントを RPC 寄りではなく REST 寄りにするのに役立ちます。実行時に使用すると、ハイパーメディアコントロール（HATEOAS とも呼ばれます）に近いものになります。クライアントがレスポンスを受け取った後、ヘッダーやデータのインスタンスとリンクを組み合わせて、次に利用できるアクションを判断できるためです。

リンティング

Spectral のような OpenAPI リンターは、API の記述が有効かどうかだけでなく、スタイルガイドなどの事前に定められたルールに沿っているかも確認できます。スタイルガイドは、大企業の API ガバナンスチームが定義したり、openapi-contrib/style-guides にあるもののように共有したりできます。

モック

記述ドキュメントを入力として受け取り、受信した HTTP リクエストをサンプルレスポンスにルーティングするか、サンプルを動的に生成する偽のサーバーです。

モックサーバーの一覧は OpenAPI.Tools で確認できます。

OAS

これは OpenAPI Specification の略称にすぎません。インターネット上の Markdown ファイルで、OpenAPI の各バージョンの動作を定義しています。

OpenAPI

別名として「OpenAPI Specification」があります。

API Description Format の新しい名称で、API Specification で定義されています。以前は Swagger と呼ばれていました。

OpenAPI Initiative

OpenAPI Initiative（OAI）は、OpenAPI Specification（OAS）の開発を管理するグループです。

Open API

オープン API は公開 API です。

OpenAPI Specification、コミュニティ、または OpenAPI Initiative を指す場合、「OpenAPI」にスペースは入りません。

パラメーター

パラメーターは、ヘッダー、パスパラメーター、クエリ文字列パラメーターをまとめて指す一般的な用語です。OpenAPI v2 では、リクエストボディ（フォームデータなど）も含まれていました。

OpenAPI v3.0 仕様のパラメーターについて詳しくはこちらをご覧ください。

リファレンスドキュメント

コードライブラリの「クラス、メソッド、定数」のドキュメントに非常によく似ており、さまざまな入力と出力を説明します。リファレンスドキュメントは、API Description を HTML（場合によっては PDF）に変換したもので、技術に詳しくない人でも API の使い方を把握できます。

リファレンス

異なる場所にある JSON 構造を指し示すことができる JSON Reference です。現在のファイル内のオブジェクトを指すことも、別の、おそらくリモートにあるファイルを参照することもあります。これは Reference Object 内にキー $ref として記述されます。例を以下に示します。

• Reference Object：{"$ref": "https://example.com/api/openapi.yaml#/components/schemas/Pet"}
• JSON Reference：https://example.com/api/openapi.yaml#/components/schemas/Pet
• JSON Pointer（参照先ファイル内の場所）：/components/schemas/Pet

解決

$ref の参照先にある値を探しますが、解決対象のファイルやオブジェクトは変更しません。

スキーマ

別名として「データモデル」もあります。

スキーマとは、データ型や、特定の形式、検証ルールなど、データに関するその他のプロパティを記述するメタデータです。JSON Schema はスキーマの一例ですが、OpenAPI には独自の JSON Schema の方言があり、schema キーワードを使用できるさまざまな場所で使われています。

スキーマは、HTTP リクエストやレスポンスの本文を記述するために使われることが最も一般的ですが、ヘッダーやパスパラメーターなどのさまざまなパラメーターを記述することもできます。

SDK

「ソフトウェア開発キット」はコンピューター分野で広く使われる一般的な用語ですが、Web API、特に OpenAPI の文脈では、通常、HTTP ライブラリのレベルではなく、プログラミング言語のレベルで他の開発者が API を利用するための何らかのクライアントライブラリを意味します。

SDK ジェネレーターの一覧は OpenAPI.Tools で確認できます。

サーバーサイド検証

データ検証の概念を使用して

サーバーサイド検証の詳細はこちらをご覧ください。

Swagger

歴史的には、「Swagger」は OpenAPI 仕様（OAS）の元の名称でした。2011 年の公開時には Swagger と呼ばれており、SmartBear が Swagger Specification を買収した後もしばらくその名称を維持し、Swagger という名前を含むさまざまなツールを開発しました。Swagger Editor、Swagger Inspector、SwaggerHub などです。

2016 年に Swagger 仕様がOpen API Initiativeに譲渡されると、名称は OpenAPI に変更されました。

現在、「Swagger」という言葉は、SwaggerHub のツールブランドの一部として使われているだけです。仕様の名称は「OpenAPI」です（OpenAPI/Swagger ではありません）。