ジャネット・ワグナー著
API 仕様と API ドキュメントの違いについてよく質問を受けます。そこで今日は、API ドキュメント、API 仕様、API 定義の違いと重要性について概説したいと思います。
API ドキュメントとは？
API ドキュメントとは、基本的に API のリファレンスマニュアルです。API の使用方法を API 利用者に伝えるものです。API ドキュメントは、通常は開発者など、人間が読んで理解するためのものです。開発者が API を快適に使用できるよう、よく設計され、包括的で、分かりやすいドキュメントを提供することが不可欠です。優れた開発者エクスペリエンス (DX) は、API の成功の可能性を高めます。開発者が API ドキュメントを理解できない場合、ドキュメントが優れていて統合しやすい別の API を探し出す可能性が高くなります。優れたドキュメントは、新しい API 利用者の onboarding にかかる時間を短縮するのにも役立ちます。開発者が API の使用に必要なすべての情報を入手できれば、企業にメールを送信したり、カスタマーサービス部門に電話をかけたり、フォーラムに投稿して助けを求めたりする必要がなくなります。
優れたドキュメントには、ここではすべてを列挙するには多すぎるほどの多くの要素が含まれています。しかし、優れた API ドキュメントを作る要素には、クイックスタートガイド、チュートリアル、インタラクティブなドキュメントなどがあり、開発者は API 呼び出しを試すことができます。API ドキュメントを生成および保守するためのツールは多数あります。これらのツールの多くは、API 定義ファイル (これについては後述します) から静的およびインタラクティブな API ドキュメントを自動的に生成できます。
API ドキュメントには、すべての呼び出し、すべてのパラメーター、および各呼び出しのレスポンスの例が記載されている必要があります。Java、JavaScript、PHP、Python などのよく使用される言語のコードサンプルを含める必要があります。ドキュメントには、各 API リクエストの説明とエラーメッセージの例を提供する必要があります。また、API ドキュメントを積極的に保守し、常に最新の状態に保つことも重要です。
API 仕様とは？
API 仕様とは、API 定義としばしば同じ意味で使用される用語です。これらの用語には多くの類似点がありますが、異なるエンティティです。API 仕様は、API の動作と API が他の API とどのようにリンクするかについての幅広い理解を提供します。API の機能と、API を使用したときに期待される結果について説明します。API 仕様の良い例は、OpenAPI Specification です。この仕様の最新バージョン (3.0.1) は GitHub で見ることができます。
ある意味では、OpenAPI 3.0.1 ドキュメントも API ドキュメントですが、API 仕様は API の動作と API から何を期待すべきかを説明しています。そして、GitHub 上の OpenAPI Specification ドキュメントはまさにそれをしています。ドキュメントには、多くの API オブジェクト、値とパラメーター、オブジェクトの呼び出し方法、各オブジェクトの動作が記載されています。また、オブジェクト間の関係と各オブジェクトの使用方法も示されています。
たとえば、リクエストボディオブジェクトセクションを見ると、このオブジェクトの動作、その固定フィールドの説明とタイプ、リクエストボディの例に関する情報が見つかります。リクエストボディオブジェクトがどのように機能するはずか、そしてこの関数を使用するときに何を期待すべきかを知ることができます。API 仕様は、API がどのように設計されているか、API がサポートするデータ型を示すものでもあります。
OpenAPI (以前の Swagger 仕様) は、いくつかの API 仕様言語の 1 つです。RAML や API Blueprint もあります。これらの API 仕様言語が 1 つの API 仕様言語である OpenAPI に収束しつつあるという勢いがあることに注意する必要があります。
API 定義とは？
API 定義は、API の構成方法と機能方法についての理解を提供するという点で API 仕様に似ています。ただし、API 定義は、API の人間による消費ではなく、機械による消費を目的としています。API 定義は、API の機能、他の API とのリンク方法、期待される結果を機械可読形式で提供します。API を定義し、API の構造を概説することに焦点を当てています。
API 定義は、多くの場合、自動化ツールのベースラインとして使用されます。API 定義を使用して、API ドキュメント、コードサンプル、SDK を自動的に生成できます。API 定義ファイルから API ドキュメント (静的およびインタラクティブ) を生成するツールの例としては、SwaggerHub や Swagger Inspector などがあります。API 定義からサンプルコードと SDK を自動的に生成できるツールの例としては、REST United や SwaggerHub などがあります。
API 定義は、仮想 API テストのためにモックサーバーにインポートすることもできます。API 定義ファイルのインポートを許可するモックサーバーと API テストのための多くのツールのうち、SoapUI と SwaggerHub があります。
API 定義は、インタラクティブなドキュメントや SDK など、API の成功を確実にする自動化ツールを強化するために使用できるため重要です。一部の開発者は、仕様言語の 1 つに基づいて最初に API 定義を作成し、次に API のコードを作成することを意味する スキーマファースト API 設計 を提唱しています。
すべて関連しているが、異なる
API ドキュメント、API 仕様、API 定義はすべて関連していますが、異なるエンティティです。そして、これらはそれぞれ重要な目的を果たします。
ドキュメントは、開発者や他の API 利用者に API の使用方法を伝えます。結局のところ、開発者が使用方法を知らなければ、API はどのように成功するのでしょうか？
API 仕様は、API の機能と期待される結果についての幅広い理解を提供します。仕様は、主に API の設計または設計哲学に関するものです。API の設計と機能は、API をアプリケーションと統合するかどうかを選択する際の重要な要素です。
最後に、API 定義は、API の機械による消費と、自動 API ドキュメントや SDK ジェネレーターなどの自動化ツールで使用するための機械可読形式の提供に関するものです。
API ドキュメント、API 仕様、API 定義はすべて、API の成功の鍵となります。
読んでいただきありがとうございます！API リソースをお探しですか？Swagger ニュースレターにご登録ください。最高の API 記事、トレーニング、チュートリアルなどを掲載したメールマガジンを毎月お届けします。購読する