企業および開発者向けAPIプロダクトおよびテクノロジープロバイダのApigeeは、Web API設計に関するフリーの電子書籍「Web API Design: Crafting Interfaces that Developers Love」をリリースした。ここには、Apigee設計ワークショップを経験した世界中のAPI設計チームの協力のもと作られたREST API設計プラクティスがまとめられている。これはBrian Mulloy氏によって書かれたもので、分量も38ページしかないので読みやすい。
ここではその概要について簡単に説明する。詳細については電子書籍を読んでほしい。この本はさまざまな設計判断について述べており、今日最も人気のあるREST APIがどのように構築されたのかを比較している。
名詞： ベースURLには動詞ではなく名詞を使い、リソース毎に2つのベースURLを使うことでそれらをシンプルに保とう。集合や要素を操作するにはHTTP動詞 (GET、POST、PUT、DELETE) を使おう。単数形よりも複数形を使おう。抽象的な名前よりも具体的な名前を使おう。例えば、以下にすべての犬と特定の犬を取得する方法を示す。
GET /dogs GET /dogs/1
本ではクライアントがすべてのHTTPメソッドをサポートしていない場合のオプションについても説明されている。
関連： リソース間の関連をシンプルにして、URL階層が深くなるのを避けよう。パラメータや属性のような複雑なものは、HTTPクエスチョンマークの後ろにもっていこう。以下は、特定のオーナーが飼っている犬すべてと、そのうち色が黒い犬を取得する方法を示している。
GET /owners/1/dogs GET /owners/1/dogs?color=black
エラー： HTTPステータスコードを使おう。ここにはHTTP 200、400、401、403、404、500が含まれる。メッセージをできるだけ冗長にしてペイロードで返そう。以下はJSONペイロードの一例だ。詳細情報についてはURLを使っていることに注意しよう。
{
"developerMessage" : "...",
"userMessage" : "...",
"errorCode" : 100,
"moreInfo": "http://developers.company.com/errors/100"
}
本ではAdobe Flashのいくつかのバージョンがそうであるように、クライアントが常にHTTP 200を期待している場合のオプションについても説明されている。
バージョン： APIのバージョニングを必須にしよう。'v' をプレフィックスとしたバージョンを指定し、それを第一階層に置こう。これはインターフェイスであって実装ではないことを強調するため、シンプルな序数を使おう。以下はAPIのバージョン1ですべての犬を取得する方法を示している。
GET /v1/dogs
部分的レスポンスとページネーション： 返してほしいフィールドを指定するには、カンマ区切りのリストを使おう。リソースのページネーションには、"limit" や "offset" を使おう。これらのパラメータは一般的であり、データベース内でも理解しやすい。以下はすべての犬の色と品種を取得する方法と、犬の最初の10個を取得する方法を示している。
GET /dogs?fields=color,breed GET /dogs?limit=10&offset=0
動詞： もしAPIがリソースではないレスポンスを送信するのであれば、名詞ではなく動詞を使った方がわかりやすい。こうしたリソースでないものに基づいたAPIがほかのAPIと違うことがわかるよう、APIドキュメントで明確にしておこう。以下は、100ユーロを中国元に変換するAPIコールだ。
/convert?from=EUR&to=CNY&amount=100
コンテントタイプ： JSONとXMLのように、APIは異なるレスポンスフォーマットをサポートすることを推奨する。どのフォーマットで返すのかを指定するには、ドット型の書式を使おう。デフォルト形式はJSONにしよう。JSONはそれほど冗長ではなく、JavaScriptで簡単に処理できるためだ。以下にXMLですべての犬を取得する方法を示す。
GET /dogs/1.xml
属性： 属性の名前付けはJavaScriptの規約に従おう。キャメルケース（CamelCase）を使おう。オブジェクトの型によって、最初の文字を大文字もしくは小文字にする。以下にユーザID属性の例を示す。
{
"userId": 1
}
検索： 複数のリソースを横断して検索するには、動詞 "search" とクエリパラメータ "q" を使おう。ドット型の書式を使って、フォーマットを指定しよう。以下に、すべての「ふわふわな毛の(fluffy)」リソースを、デフォルトフォーマットとXMLフォーマットで検索する例を示す。
GET /search?q=fluffy GET /search.xml?q=fluffy
検索にスコープを追加するには、クエリパラメータをもつリソース指定のURLを使うことができる。たとえば、ある特定のオーナーが飼っている「ふわふわな毛(fluffy)」の犬すべてを検索するには以下のようになる。
GET /owners/1/dogs?q=fluffy
サブドメイン： すべてのAPIリクエストをひとつのAPIサブドメインにまとめよう。api.company.comのようなものを使うのだ。developers.company.comのような開発者専用ポータルも作ろう。ユーザがブラウザでAPIサブドメインを開いたら、開発者ポータルへリダイレクトしてもよいだろう。
認証： 標準のOAuth 2.0を利用しよう。パスワードを共有することなくAPIアクセスが可能になる。APIプロバイダはアクセストークンを無効にできる。開発者はほかのAPIで使っているのと同じOAuthライブラリを使える。
おしゃべりなAPI： あまりにおしゃべりなAPI設計もある。つまり、単純なアプリケーションを構築するのに、何度もサーバにAPIコールをする必要があるのだ。完全でRESTfulなAPIを作り、必要に応じてショートカットや合成したレスポンスを提供することを推奨する。
SDK： APIプロバイダはサンプルコード、ライブラリ、ソフトウエア開発キットでAPIを補足することを推奨する。そうすれば具体的なプラットフォームにすばやく導入できる。サービスをスローダウンさせるおそれのある、まずいコードや非効率なコードを削減するのにも役立つ。異なる開発者コミュニティにAPIを売り込むのにも役立つ。
API Facade： APIの構築方法にはいろいろある。おすすめのアプローチは "API Facadeパターン" と呼ばれるものだ。これは次の3つの基本ステップからなる。
- 理想的なAPIを設計する。URL、パラメータ、レスポンス、ペイロード、ヘッダーなどを設計する。
- スタブを使って実装する。こうすることで、まだAPIが内部システムにつながっていなくても、開発者はAPIを使ってみることができ、フィードバックを返すことができる。
- そのFacadeと内部システムを統合する。
APIを直感的でアプリ開発者にとって使いやすいものにすることが目標だ。
電子書籍 Web API Design はApigeeのWebサイトからダウンロードできる。コメントや提案については API Craft Google Groupにアクセスしよう。