はじめに
クラウドの普及や特色のあるWebサービスが次々と登場してきており、それらのWebサービスが外部との連携のために公開されているWebAPIも急増しています。
これらのAPIの仕様は、一般的にはAPIリファレンスという形式でサービス内のWebページに公開されていたり、Githubに公開されていたりとサービス事業者毎に標準化がなされていない様々な形式で公開されています。近年、これらのWebAPIの記述を標準化する流れが進んでおり、いくつかの統一的な記述言語が出てきておりますので、本記事では代表的なものを紹介したいと思います。
標準化の価値
Webサービス毎のバラつきを無くすことで、異なるWebサービスのAPI仕様を透過的に参照することができるようになります。それにより、Webサービス間のデータ連携や異なるWebサービスを組み合わせて新しいサービスを創り上げるマッシュアップが容易となります。また、小さなサービスを組み合わせて大きなサービスを作り上げるマイクロサービス化時のサービス間インタフェースの共通仕様の理解の面でも標準化は重要です。
API管理プロダクトとの関係
最近のAPI管理サービスや製品には、標準的なAPI記述言語で作成されたドキュメントの生成に加えて、これらのドキュメントから各言語毎のサンプルコードを出力したり、API記述言語のプレビュー機能がついたエディタが備わっており、API記述標準が前提となっています。また、これらのプロダクトは、APIモックサーバーを立て上げることで、API記述標準でエンドポイント、リクエスト時のパラメータ、レスポンスフィールドを定義することでAPIの実装がまだでも並行してクライアントサイドの実装を進めることができます。
API記述標準の代表例
・Swagger ※Open API へ名称が変更
・API BluePrint
・RAML
Swagger (Open API)
API技術標準のリーダー的な存在。記述フォーマットはYAML言語。ライセンスはApache 2.0。Swaggerは、RESTful APIの設計、構築、文書化、および使用に役立つ、大規模なエコシステムツールを使用した強力なオープンソースフレームワークです。Swaggerにはコアとなるツール群が備わっています。
主なツール一覧
| 種類 | ツール名称 | 説明 |
|---|---|---|
| Design | Swagger Editor | API記述標準言語をプレビュー画面で確認しながら生成 |
| Build | Swagger Codegen | API記述標準言語から主要言語のサーバスタブやクライアントSDKを作成 |
| Document | Swagger UI | API記述標準言語から生成されたHTMLベースのAPIリファレンス |
Swagger Editorで作成したAPIドキュメントの例
2015年にLinux Foundationの協力のもとSwaggerをベースにしたAPI記述標準を推進する団体である「Open API Initiative」が結成されました。パートナーとしては Google、Microsoft、IBM、3Scale(redhat)、Apigee(Google)，SmartBearが名を連ねており、swaggerのサイトはSmartBear社が運営しています。
API BluePrint
マークダウン形式の記述標準言語で人間が読みやすいヒューマンフレンドリなフォーマットを強みとしています。ライセンスはMITライセンス。
モックアップサーバーやドキュメントの作成は、Webページ内のTools selectionに一覧化されたApiaryなどの数多くの周辺プロダクトから選ぶことができる。
RAML
RAMLは「RESTful API Modeling Language」の略で、YAMLベースのAPI記述標準言語。ライセンスはApatch2.0。
API管理のリーディングカンパニーであるMuleSoftがツール群をAPI Designerやモックアップサーバーなどの周辺プロダクトを提供して普及を推進しています。
まとめ
上記でご紹介した３つはあくまで代表的なものであり、そのほかにも各Webサービス提供元やAPI管理プロダクトベンダが提供している記述標準は多く存在しており、JSON部分に特化した記述標準であるJson Schemaなど様々です。参加企業を見るとSwagger(OpenAPI)が本命に思えますが、今後、どれがスタンダードになっていくのかウォッチしていく必要がありそうです。