Qiita Teams that are logged in
You are not logged in to any team

Log in to Qiita Team
Community
OrganizationAdvent CalendarQiitadon (β)
Service
Qiita JobsQiita ZineQiita Blog
Help us understand the problem. What is going on with this article?

RESTful API記述標準について

More than 3 years have passed since last update.

はじめに

クラウドの普及や特色のあるWebサービスが次々と登場してきており、それらのWebサービスが外部との連携のために公開されているWebAPIも急増しています。
これらのAPIの仕様は、一般的にはAPIリファレンスという形式でサービス内のWebページに公開されていたり、Githubに公開されていたりとサービス事業者毎に標準化がなされていない様々な形式で公開されています。近年、これらのWebAPIの記述を標準化する流れが進んでおり、いくつかの統一的な記述言語が出てきておりますので、本記事では代表的なものを紹介したいと思います。

標準化の価値

Webサービス毎のバラつきを無くすことで、異なるWebサービスのAPI仕様を透過的に参照することができるようになります。それにより、Webサービス間のデータ連携や異なるWebサービスを組み合わせて新しいサービスを創り上げるマッシュアップが容易となります。また、小さなサービスを組み合わせて大きなサービスを作り上げるマイクロサービス化時のサービス間インタフェースの共通仕様の理解の面でも標準化は重要です。

API管理プロダクトとの関係

最近のAPI管理サービスや製品には、標準的なAPI記述言語で作成されたドキュメントの生成に加えて、これらのドキュメントから各言語毎のサンプルコードを出力したり、API記述言語のプレビュー機能がついたエディタが備わっており、API記述標準が前提となっています。また、これらのプロダクトは、APIモックサーバーを立て上げることで、API記述標準でエンドポイント、リクエスト時のパラメータ、レスポンスフィールドを定義することでAPIの実装がまだでも並行してクライアントサイドの実装を進めることができます。

API記述標準の代表例

SwaggerOpen API へ名称が変更
API BluePrint
RAML

Swagger (Open API)

image

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ドキュメントの例
image

2015年にLinux Foundationの協力のもとSwaggerをベースにしたAPI記述標準を推進する団体である「Open API Initiative」が結成されました。パートナーとしては Google、Microsoft、IBM、3Scale(redhat)、Apigee(Google),SmartBearが名を連ねており、swaggerのサイトはSmartBear社が運営しています。
image

API BluePrint

image

マークダウン形式の記述標準言語で人間が読みやすいヒューマンフレンドリなフォーマットを強みとしています。ライセンスはMITライセンス。
image
モックアップサーバーやドキュメントの作成は、Webページ内のTools selectionに一覧化されたApiaryなどの数多くの周辺プロダクトから選ぶことができる。
image

RAML

RAMLは「RESTful API Modeling Language」の略で、YAMLベースのAPI記述標準言語。ライセンスはApatch2.0。
image
API管理のリーディングカンパニーであるMuleSoftがツール群をAPI Designerやモックアップサーバーなどの周辺プロダクトを提供して普及を推進しています。

まとめ

上記でご紹介した3つはあくまで代表的なものであり、そのほかにも各Webサービス提供元やAPI管理プロダクトベンダが提供している記述標準は多く存在しており、JSON部分に特化した記述標準であるJson Schemaなど様々です。参加企業を見るとSwagger(OpenAPI)が本命に思えますが、今後、どれがスタンダードになっていくのかウォッチしていく必要がありそうです。

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away