Qiita API v2のJSON Schemaを公開しました
こんにちは、r7kamura です。
最近は主にイカとして活動しており、カラフルな墨を掛け合う日々を送っています。
さて、QiitaおよびQiita Teamでは、Qiita API v2としてデータを操作するためのREST APIを公開しています。これまで開発者向けに APIドキュメント を提供していましたが、今回は主に機械向けのインターフェースとして、JSON Schemaで記述したREST APIのスキーマ定義 (以下スキーマ) を公開することになりました。具体的には、JSON Hyper-Schema draft v4 を利用して定義されています。
http://qiita.com/api/v2/schema
Qiita API v2のスキーマの説明
Qiita API v2のスキーマの構成について簡単に説明します。スキーマは http://qiita.com/api/v2/schema から取得できます。localeというURLクエリパラメータで日本語および英語を指定できるので、使いやすいほうをご利用ください。以下の例では、curlを利用してスキーマを取得しています。容量が少し大きく、改行などを含んでいないため、jq や less を利用すると少し読みやすくなるかもしれません。
$ curl http://qiita.com/api/v2/schema
$ curl http://qiita.com/api/v2/schema?locale=ja
$ curl http://qiita.com/api/v2/schema?locale=en
$ curl http://qiita.com/api/v2/schema?locale=en | jq .
$ curl http://qiita.com/api/v2/schema?locale=en | jq . | less
スキーマの中身は、以下のような構成になっています。最上位のpropertiesプロパティの中で、アクセストークンや認証済みユーザ、コメントなど、APIでどのようなリソースが提供されるかが示されており、また各リソースがどのようなプロパティを持つか、どのようなリンクを提供しているか、ということが定義されています。 http://qiita.com/api/v2/docs もこのスキーマを元に生成されているので、ドキュメントと照らし合わせながら読むと分かりやすいかと思います。
{
"description": "...",
"properties": {
"access_token": {
"description": "...",
"links": [...],
"properties:" {
"client_id": {...},
"scopes": {...},
"token": {...}
},
...
},
"authenticated_user": {...},
"comment": {...},
"expanded_template": {...},
...
},
"title": "..."
}
JSON Schemaの使われ方
スキーマには、どのようなリソースがAPIで提供されるか、それらがどのように表現されるか、それらを操作するためにどのようなエンドポイントが提供されているか、といった事柄が記述されています。
JSON Schemaのよく見る使われ方としては、任意のプログラミング言語用のクラスファイルをそこから生成したり、ドキュメントを自動生成したり、受け入れテストを用意したりといった例があります。Qiitaでも、APIドキュメントをスキーマから自動生成したり、Kobito for Mac用にObjective-Cのクラスファイルを生成したり、Kobito for Win用にAPIクライアントを生成したり、といった使い方をしています。例えば、以下のクライアントライブラリの一部の実装は、スキーマをもとに生成されています。
- https://github.com/increments/qiita-rb
- https://github.com/increments/qiita-js
また、Qiita API v2自身もJSON Schemaを元に実装やテストが用意されており、クライアントから送信されたデータの検閲に利用したり、定義されているインターフェースと異なるデータを返すような実装になっていないかどうかを確認したり、といった使い方をしています。実際には、以下のライブラリを組み合わせて実現しています。Rubyで書かれたリソース定義用のクラスがあり、そこからJSON Schemaを生成し、それをドキュメント生成やバリデーションの仕組みに利用しています。
- https://github.com/r7kamura/jdoc
- https://github.com/r7kamura/json_world
- https://github.com/r7kamura/rack-json_schema
なぜJSON Schemaを選んだか
まずスキーマを定義するに至った理由は、実装効率とコミュニケーションの問題です。
Web APIを提供するには、Webアプリ側で一貫性のあるWeb APIを実装して、テストを用意して、互換性のあるAPIドキュメントを用意して、それを利用するクライアントライブラリを用意して、クライアントアプリの開発用にダミーサーバを用意して、更にAPIに変更を加える際にはこれら全てが保たれるように慎重に処理を加えなければなりません。Incrementsのエンジニアは数人程度の規模ですから、あまり多くの労力は傾けられません。
また、多くの場合クライアントアプリケーションとWebアプリケーションの開発者は別々の人間が担当することになります。そのため、属人性を排し作業を円滑に行うために、1つの決められたプロトコルを元に作業を進められることが求められていました。そのようにWeb APIの仕様を決まった形式で記述する手段として、以下のような候補を考えました。
- JSON Schema
- RAML
- WADL
- Swagger
- Apiary
- 独自フォーマット
そこで、選定にあたって以下のような要件を考えました。
- スキーマからドキュメントを生成できること
- スキーマから他の言語のクライアントを生成できること
- スキーマからValidationルールを生成できること
- スキーマからテストを生成できること
- 知識を他で再利用・共有できること
- 自分でも全てのライブラリを実装できること
- 人間が読みやすいこと
- 機械が読みやすいこと
- すぐ捨てられること
これらの要件を満たす手段として、最終的にJSON Schemaに落ち着きました。
まとめ
Qiita API v2のスキーマを公開した旨をお知らせしました。JSON Schemaはほどほどに分かりやすく、ドキュメントや、テスト、バリデーション、コミュニケーションの道具として機能しています。公開しているスキーマは、JSON Schemaのサンプルとして利用したり、何か面白いものをつくってもらえると幸いです。公開した直後は、しばらくのあいだ些細な修正が加えられるかもしれませんが、ご理解いただければと思います。
よしけんです。
r7kamuraです。