良い Web API の5つの条件

ども、@kimihom です。

私は仕事柄、色々な API の仕様を見て実装するようなことをしている。そこで感じる「個人的にあったら嬉しい Web API の機能」について語っていきたい。

1. API とドキュメントが無償で公開されている

Web API の資料が誰でもアクセスできるようになっていること。そして開発者は無償でその開発環境を手に入れられること。これが一つ目の条件だ。

至極当たり前のように思えるんだけど、そうじゃないところが結構あるので、一番先に書いた。API を公にせずにドキュメントは担当者とのやり取りでメールの添付 PDF ファイルにまとめられているとか普通に存在する。または、API を使うのに有料契約しなければ開発する環境すら用意できないところもあったりする。

Web API は色々な企業が自由に開発し、連携できるようになって欲しいと強く願う。一部の企業にだけ契約書を交わして特別公開みたいなクローズドな世界では、開発者だけでなくユーザーの選択肢を限定してしまう。特に SaaS 系だったら顧客やタイムラインなどで連携できたら良いのにと思うことがたくさん出てくるが、その企業が自由に利用できる API を公開していないために自社のユーザーを困らせる原因を自ら作っているのである。

こういう企業ってのは大抵は「ユーザーを囲みたい」っていう理由でクローズドにしているか公開していなかったりするんだけども、自社であらゆるニーズを満たすサービスをすべて実現するのは、それぞれの規模、業種、スキルがある中で不可能だと早めに気づいていただきたい。オープンな Web API を公開し、誰もがあらゆるサービスと気軽に連携できるものが求められているのだ。

2. 認証の仕組みがしっかりと用意されている

基本的に Web API の認証方法はトークン方式か OAuth2 認証かの2つになる。個人的にはこのどちらも用意していただけるとありがたい。もちろんトークン認証はセキュリティ的に危うい点があることは承知だが、トークンをセキュアに管理することで手に入れられる手軽さをは大きい。テストも簡単にできるし、変に有効期限とかを気にしなくて良いので安心して実装できる。

トークンをさらに独自に暗号化してリクエストを POST で送ってくださいみたいな API に遭遇したことがあるが、何のための予測不能なトークンを生成しているのかよくわからないので、トークンを付与するだけでレスポンスを返せるようにして欲しい。

OAuth 認証は正しく OAuth になっているものにして欲しい。たまにアクセストークンとリフレッシュトークンの使い方を勘違いした API を見ることがある。リフレッシュトークンはあくまでアクセストークンの有効期限が切れた時に再発行するためのトークンであり、普段のリクエストでリフレッシュトークンの送信も必須にするなどはして欲しくない。

トークン、 OAuth2 に限らず、利用できるスコープが用意されていると安心できるので尚良い。ここは API の機能が多い場合とかは必須になる項目かと思う。

3. リソースを検索するための手段がある

割とありがちなのは、一覧 API と ID で限定するだけの API しかないケース。これだとリソースをどうやって検索すれば良いのか困るケースが多々ある。

例えばメールアドレスや電話番号による検索、作成/更新された順番で取ってこれる検索といった利用頻度の高そうな限定的なものを提供する API があると良い。何でも OK なフルテキスト検索 API もあると便利だ。そのような検索によって対象のリソースを見つけ出し、外部から適切な処理を行うことができる。

個人的には指定更新日時より新しいリソースを一括でとってくる API はあるととても嬉しい機能である。(リソースの同期を実現する上で必要)

4. リソースを Insert or Update できる API がある

あると結構嬉しい InsertOrUpdate API。毎回 API で対象のリソースが存在したら更新、しなければ作成みたいな処理を書くのが面倒だ。そんな時には例えばメールアドレスをキーとして、存在すれば更新、しなければ作成を勝手にやってくれる API があると嬉しい。そして ID をレスポンスで返すといった形だ。

当然 Create だけの API で既にあったら例外を吐くような API もあるべきなので、両方あると良いと思う。もっと言えば Web 上ではできるのに API ではできない機能が無いように網羅したいところだ。

4, マスタデータ作成 API の手間を考慮している

例えば複雑な関連のある API である場合、ベースのリソースを作成して、その次に種類のリソースを作成して、最後にようやく目的のリソースを作成できるような API があったとする。

この時に毎回ゼロから組み立てるのは大変なので、ベースとなる部分は開発者の Web コンソール上でサクッとデフォルト値的な感じで組み立てられるようにできているとありがたい。 API で呼ぶ必要があるのは、最後の目的のリソース作成だけで、他は事前に作った固定値 ID を指定すれば良いだけみたいになっていると嬉しい。ゼロから全部作らないといけない API は、そのぶんたくさんのリクエストを送る必要があり、エラーハンドリングのことを余計に多く考えなければいけないので辛くなる傾向にある。あらかじめ最初のマスターデータ的なのは作っておけるようにすれば、このような心配もいらくなる。

5, エラーメッセージが適切

API を組み立てて実験をしていると、うまく API リクエストを送れていないことが頻繁に起こる。そん時にちゃんとしたエラーメッセージが出ていることは良い Web API の条件だ。たまに 200 を返すのにメッセージなしで失敗しているみたいなケースがあったりして、このような場合には無駄に多くの時間を割かなければならなくなってしまう。

これはどこまでエラー処理を考慮しているかってのにもよると思うけど、API 機能として最低限のエラー対策はやっておいて欲しいと思う。