色んなWebサービスのAPIを使ってみて

背景: 沢山のWebサービスのAPIを使ってる

色んなサービスのデータを集めて、横串検索出来るようにしてる

GitHub (issue, PR のコメント, wiki ページ), Slack, Google Drive etc. のデータをAPI経由で集めてきて、横串検索出来るようなサービスを作ってる。

こちら → Commet

経緯はこんな感じ。

• こんなサービスあったら便利かも。作ってみよう。
• とりあえず出来た。うん。そこそこ便利。
• デザインとかできてないけど、ブログで軽く告知してみよう。→ 特に反応無し。
• まぁ、誰も使ってくれなくても、最悪自分で使ってるし、ちょこちょこ改善して、適当なタイミングでもう一度宣伝しよう
• 自分で使いつつ、色々修正（長い時間が経過・・・）
• いい加減、デザインとか綺麗にして、一般公開しよう。← イマココ

ということで、もう少し体裁を整えてから、ちょっと宣伝とかしてみようと思ってる。

が、今回の本題は、技術的な話。

当然、色んなAPIを使ってる

色んなサービスからデータを集めるので、当然、色んな API を使わなければならない。現在、以下のサービスのAPIを使って、データを取ってきている。

• GitHub (issue, PR, wiki)
• Slack
• Bitbucket (issue, wiki)
• ChatWork
• Backlog (issue, PR, file)
• Google (Drive, Gmail)
• Facebook (グループ)

（その他、webhook 経由で Redmine にも対応しているけど、詳細は省略。）

これだけ色々使ってみると、それぞれの API の癖や、長所・短所などが見えてくるので、そういう事について書いてみる。

独断による使いやすさランキング

とりあえず、個人的に使いやすさでランキングを付けてみようと思う。

評価ポイントは以下の通り。

• 必要な情報が API で取得できるか
• 使いやすいインターフェースか
• (Java/Scala の)公式ライブラリはあるか。ある場合は使いやすいか
• ドキュメントは分かりやすいか

まずは結果から。

• Aランク: GitHub, Slack, Google, Facebook
• Bランク: Bitbucket, ChatWork
• Cランク: Backlog

Aランクの中でも、GitHub, Google, Facebook が更に上をいっている感じではある。

各 API についてコメント

GitHub

必要な情報が API で取得できるか

Yes. つい最近、Amazon では、各サービスは全て（外部に公開しているのと同じ？） API 経由でデータをやり取りしてるって記事を見たけど、GitHub もそんな感じなのかなと想像。API で必要なデータは大体取得できるので、実装上は大きな問題はなかった。

API ではないけど、web hook で wiki ページの作成、更新内容が送れれば言うこと無いんだけど。

使いやすいインターフェースか

Yes. オーソドックスな REST API という感じで、使いやすい。

公式ライブラリはあるか。ある場合は使いやすいか

No. 公式ライブラリはあるが、Java/Scala のものは無い。が、超有名なサービスなので、当然サードパーティライブラリは存在する。詳細はライブラリページを参照。

ちなみに、Commet では、そうしたライブラリは使ってない。使いやすい API だし、自作のクラス（200行程度）で間に合ってる。

ドキュメントは分かりやすいか

Yes. さすが、優秀な開発者が揃っているだけあって、開発者向けのドキュメントは分かりやすい。

Slack

必要な情報が API で取得できるか

Yes. プラットフォーム戦略を進めてるみたいで、API はどんどん機能が充実していっているっぽい。

使いやすいインターフェースか

Yes. 分かってしまえば使いやすいが、種類が沢山あるので、最初は迷うかもしれない。

公式ライブラリはあるか。ある場合は使いやすいか

No. 公式ライブラリはない。が、オープンソースのライブラリはたくさんある。（が、Commet ではそれらは使っていない。）

ドキュメントは分かりやすいか

Ok. 必要な情報は網羅されているが、GitHub に比べると、メニュー構成が若干分かりにくいかも。

Google

必要な情報が API で取得できるか

Yes. GitHub と同様でデベロッパーフレンドリー。

使いやすいインターフェースか

Yes. ただし、API の数が膨大で、OAuth のスコープも一杯あるので、ちょっとめんどくさい。

公式ライブラリはあるか。ある場合は使いやすいか

Ok. 公式ライブラリはあって機能的にも問題ないけど、あまりメンテされていない？ライブラリのドキュメントはいまいち。もちろん、サードパーティのライブラリも大量にあるので、全般的には問題なし。

ドキュメントは分かりやすいか

Yes. ただし、前述の通り、API の数が膨大なのと、互換性のために API のバージョンも複数あるので、必然的に複雑になりやすい。

Facebook

必要な情報が API で取得できるか

Ok. 超巨大なユーザーベースを持つ SNS なので、当然セキュリティだのプライバシーなども厳しいのと、ビジネス上の戦略のせいか、 API で取得出来る情報にも結構制限がある。また、 API バージョンが上がる毎にそれらはより厳しくなってきて、審査が必要な API も増えてきている。

ただ、それは技術的なものというよりは、ビジネス上の制約なので、まぁ仕方ないかという気もする。

使いやすいインターフェースか

Yes. 難をあげれば、種類が多いのと、バージョンが頻繁に上がること。

公式ライブラリはあるか。ある場合は使いやすいか

No. Java/Scala 以外は、色々ある。詳細はこちらを参照。

ドキュメントは分かりやすいか

Yes. パラメータ・戻り値の型などもしっかり書いてある。

Bitbucket

必要な情報が API で取得できるか

Yes. 後述の分かりにくいインターフェース・ドキュメントにめげなければ、必要な情報は取得可能。

使いやすいインターフェースか

No. 良くない点をいくつか挙げる。

• このエンドポイントにこの情報含まれてないの？ってのが結構ある
• Version 1 と 2 があるが、1 でしか取れない情報とかがある

公式ライブラリはあるか。ある場合は使いやすいか

No. （多分）

検索してもよく分からず。Commet では、自前のクラスを使ってる（大したサイズではない）。

ドキュメントは分かりやすいか

No. 分散してるし、必要な情報が含まれていない。

ChatWork

（情報開示: 仕事で関わりあり）

必要な情報が API で取得できるか

Yes. （多分）

自分が必要な情報は取れている。そもそも、API的にはそれほど機能が多いサービスではないし。

使いやすいインターフェースか

No. 改善してほしい点は以下の通り。

• OAuth に対応して欲しい
• REST じゃない

2番目についてだが、具体的には、あるチャットルームのメッセージ一覧を取得するエンドポイントの挙動が、以下のようになっている。

• パラメータを渡さなければ、前回取得分からの差分のみを返す
• force パラメータを渡すと、前回実行に関わらず、最新の100件を取得

分かりにくいし使いづらい。

公式ライブラリはあるか。ある場合は使いやすいか

No. とりあえず、自分が必要な機能のみを実装したライブラリを公開している。
→ chatwork4s

ドキュメントは分かりやすいか

Yes. レイアウトが若干分かりにくいが、必要な情報は得られる。

Backlog

必要な情報が API で取得できるか

Ok. サービスとして機能が多いのはわかるが、取れない情報も結構ある。具体的には、pull request のコメントで、コードのどの部分に対するコメントなのか、という情報が取れないのがつらい。

使いやすいインターフェースか

No! これは、全力で No と言いたい。以下、いくつか例を挙げる。

• 結果をソートできないエンドポイントが多い
• ステータスなどによってフィルターが出来ないエンドポイントも多い
• 更新日がXX以降、というような指定が出来たとしても、日単位でしか指定できない

公式ライブラリはあるか。ある場合は使いやすいか

No. backlog4j というのはあるが、色々問題がある。覚えているのだけでも

• JavaDoc が無い
• API レスポンスのあるフィールドに null が入ることがあるかどうか、実行してみないと分からない
• あるエンドポイントに対するパラメータを表す XxxParams というクラスがあるが、サーバー側で実装されていないパラメータがあるらしく、そのクラス経由でパラメータを渡すと、unknownParameter が返ってくる
• オーバーロードを使わず、Object 型の引数を受け取るメソッド

最後のやつをちょっと説明。Backlog のプロジェクトや issue には、内部的に使われている ID (integer) と key (プロジェクトの場合は 3文字の英数字) があって、どちらを渡しても必要な情報が取れるようになっているが、backlog4j のメソッドのシグニチャはこんな感じ。

ResponseList<IssueComment> getIssueComments(Object issueIdOrKey) throws BacklogException;

int issueId を受け取るメソッドと String issueKey を受け取るメソッドの2つを作れば良いと思うんだけど。

ドキュメントは分かりやすいか

No. ドキュメントはこちら。分かりにくい点をいくつか挙げる。

• 右側のメニューがグループ化されて無くて、必要な情報にたどり着くのに時間がかかる
• レスポンスは、例として JSON が載っているだけで、型が分からない
• レスポンス例の JSON には全てのフィールドが記載されているとは限らないので、実際に実行してみないと、どのような値が返ってくるかが分からない

使いやすさが違ってくる理由

API の使いやすさは、そのベンダーの

• API を重視しているかどうかのスタンス
• 技術力

が反映されていると思う。

Backlog は API を重視していないのは分かるし、API によるビジネス展開とかもあんまり想像付かないので、APIが使いにくいのは諦めるしかないのかもしれない。

ChatWork は、チャットを中心としたプラットフォーム戦略を進めるって方向性もありそうなので、API は是非改善して欲しい。

Bitbucket というか Atlassian は技術力もあるし API を充実させるメリットもあるはず、というのを考えると、API の残念っぷりは際立つ。

雑感

今後、色んなシステムがどんどん連携していくと思うので、API って重要だなーと改めて思った。で、使いにくい API を提供しているベンダーは、そういうチャンスを逃しているってのに気づいた方が良さそう。

今後

API を使うだけでなく、公開もしてみたい。