“API design for humans” をざっくり日本語にしてみた

Time to Read

8分

37signals Signal vs. Noise で投稿されたブログ記事、面白そうなので日本語にしてみた。特に許可をとってたりとかしてないし、そんな厳密に原文をなぞってないですけど、まあ緩く。原文を必ずあわせて読みましょう。

37signals でデータを取り扱う仕事の終着点のひとつとして、たくさんのバラバラの API を取り扱うことがある – 私は少なくともこの数か月間で、10以上のサードーパーティ API を利用し、それと同時に我々の持っているすべてのパブリック API と、さらに多様な内向けインターフェースを取り扱ってきた。いくつもの違った言語で書かれたラッパーを利用し、いくつかは自分自身で書いた。こんな私が API の設計 – デザインとドキュメントに関して、利用者として強い意見を持っていたとしてもおかしくはないだろう。

私の経験上、 API のユーザビリティに真に関係する要素がいくつかある (何が真に REST であるか、 XML と JSON のどっちが技術上素晴らしいかは別の人に譲る) 。

もっと教えてよ: ドキュメントが一番大事

実際の API のデザイン (下を参照) を好む人もいるだろうが、私はまずクリアなドキュメントの方を選ぶ。「クリアな」ドキュメントというものは以下のようなものだ:

リクエストについての情報を完全に含むサンプル。例えば、我々の API ドキュメントが提供するような curl を用いた完全なサンプルのようになるだろう。もしくは、 Campaign Monitor がやっているように、各メソッドに対しわかりやすいリクエストの記述を書くと良い。
どのようなレスポンスが想定されるかのサンプル。APIドキュメントを読んでいてもっともイライラすることの一つに、APIを使った際にどんなレスポンスが返ってくるか分からないことがある。モックデータを示すのは一つの手段だろう。この原則に沿った良い API ドキュメントとは、 API にただの一回もリクエストを投げなくとも、ラッパーが書けてしまうようなものだろう。Campaign MonitorとMailChimpは、それぞれ別々の形で大変良い例を持っている。
エラーコードのリスト、それらがどういう意味か、そしてそれらが主にどういったときに起こりうるか。私はAdwords APIのファンというわけではないのだが、そのドキュメントはあらゆるレスポンスコードを詳細に書いているという点で素晴らしい例だ。
検索可能な HTML のインタフェース。視覚的に素晴らしくても実際には意味がない。それに、 Google はたくさんの検索結果をインデックスしてくれる。私にとってイケてないのは、 API ドキュメントが PDF であったり、閲覧するのに認証が必要だったりすることだ。
バージョンと、それらの廃止のスケジュール。バージョンを付けるのがいいか、徐々に進化させるのがいいか、についてはいくつか議論があるが、当然のこととして、あなたが誰か他の人のコードに影響するような変更を加える場合は、適切な警告を出し、ドキュメントのウェブサイトにも注記をすべきである。時には、セキュリティ的な理由での変更で、事前通知ができないような場合もあるだろうが、可能であれば数週間の通知をすれば多くの人に広まるだろう。Github API はいつ、どの機能が停止されて、どういう違いがあるかを明確に書いている。

入れてくれよ: 認証について

ほとんどの API は OAuth/OAuth2 や、 HTTP の基本/ダイジェスト認証でユーザーパスワードや API トークンを渡すなどの方法、もしくは各リクエストに特別なパラーメータを加えさせる方法を用いている。それぞれに長所/短所がある:

OAuth と、まだ開発の続く OAuth2 は、サードパーティ製のアプリケーションから API を利用させるような場合のデファクトスタンダードとなりつつある。これはセキュアで、比較的利用者にやさしく、比較的使いやすい。悪いところとして、各サービスプロバイダで微妙に実装のされ方が違っている点がある(常套句として「ドキュメントが実装なんだ」というのがある)。それにより、あなたの欲しいほんの少しのデータを得るためのオーバーヘッドが発生しがちである。
ユーザ名/パスワード、または API 用トークンを基本認証やダイジェスト認証で渡す方法は、高速だし、 curl だけで試せるし、さらに言うとブラウザだけで検証できる。とはいえ、エンドユーザに API トークンを探すように頼むのは、あまり「親切」ではない、と言える。
ユーザ名/パスワード、または API 用トークンを URL のパラメータに含めるやり方はあまり一般的ではない。基本認証より分かり辛いし、同じようなデメリットがあるし、しかも長所がないからだ。

トレードオフがここに存在する – OAuth はサードパーティに認証機能を分け与えるには素晴らしい仕組みだが、 API トークンはあなた固有のデータにアクセスするためには素早くできる。私の好みとしては、 API は複数の認証方法を提供してほしくて、そうすればあなたがやりたいことにとってベストな手段を選択できるからだ。

デザインの奥にあるもの: REST 、もしくはそれに似た何か

RESTの公式な定義はあるにはあるのだが、ある API が真に RESTful であるかどうかについての議論は後を断たない。 API 利用者としては、実際のところそれが技術的に完璧に RESTful であるかどうかは気にしてはいないが、 “REST っぽい” 要素についてはいくつか重要なものもある:

SOAP ではないこと。SOAP API が存在していることに利にかなった説明があることは知っている。で、たくさんのレガシーな SOAP API を REST に移行するのは大変難しいことも想像がつく。だが、スクラッチからクライアントライブラリを書いたり、何か特殊なことをしたい場合、 SOAP の API を利用して実現ことは大変難しい。
「HTTP の動詞」の意味のある使い方。Adwords APIどんな API 利用者も、 GET, POST, PUT, DELETE を使うことができ、そしてそれによりそのリクエストが何をするか、を非常に明確にできる。 GET リクエストで既存のデータを変えてしまうような API は大変恐ろしいものだ。
リソースの名前に鋭敏であること。気の回されたリソース名や path (たとえば、 /api?type=posts&id=23 の代わりに /posts/23 を用いること) は、これもまたそのリクエストが何をするかを明確にする。 URL パラメータはフィルターを行う場合には素晴らしいが、何もかもが単一のAPIエンドポイントと大量のパラメータで構成されているのでは、あっという間に利用するために必要なメンタルモデルは複雑怪奇なものになってしまうだろう。私は、 Assistly がやっているような API リソース path と、HTTP verbの使い方を好ましく思う。
XML と JSON について。私は JSON が好きだが、 XML が好きな人もいる。両方を提供するコストが高すぎない限りは、両方を提供しよう。理想的には、 URL の拡張子を .xml から　.json にするだけでフォーマットを変えられるようにしてほしい。
便利であれば、抽象化を行う。あなたの API の実装は、あなたが今動かしている実アプリケーションの構成をそっくりそのまま真似する必要はないということ。たとえば、 Adwords API には 25 個の別々の “サービス” があり、それぞれがすでにある実装と対応した一つのモジュールであるように見える。これは、あなたが実装するぶんには合理的であろうが、使う分には親切とは言い難い – もしあなたが運用している各広告のクリックスルーレートを取得したいと思ったならば、(文字通り) 何十回もの別々のリクエストを作成しなければならない。一方、 Google Analytics data export API はあなたにレポートの内容を定義させ、そうすることであなたは滅多に1回よりも多くのリクエストを送る必要がなくなる。それでも、あなたは必要なデータを取得することができる。もし、あなたが、ユーザが共通で行うようなひとまとまりの操作がいくつか存在すると考えたのならば、たとえ「理念」に反することになるとしても、その操作を容易に実行できるようにすべきだ。

これらは、私の好みに過ぎないし、 API の設計に堅牢で高速なルールなど存在しない。ただ、これらの原則をあなたがこれから作る API に当てはめようが当てはめまいが、私は「利用者」の立場から API を見てみることをお勧めしたい。たぶん、小さな何かアプリを自分自身の作った API で作ってみるのが良いだろう – 目を見開かれるような体験になるはずだ。