メーリングリストやフォーラムでは、RESTとWeb APIにまつわる問題について様々な議論がなされています。これからお話するのは、こうした問題に対する私の独断的意見です。これには絶対的な正解というのはありません」InfoQの主任コンサルタントであるOliver Wolf氏は、GOTO Berlinカンファレンスの彼のトーク ”Web API DOs and DON'Ts" でこう語り始めた。
エンドポイント観点で考えてはいけない。SOAPは見かけ上、単一のエントリーポイントを持つ。これに対し、Webは多数のエントリーポイントを持ち、ハイパーメディアを重要な構成要素として用いたリレーションやインターコネクションにより構築されている。APIを一方向のみのブラックホールにするのではなく、ハイパーメディアコントロールを使って、利用者にとって意味のあるやり方で、リソース表現にリンクしなくてはならない。
APIでドメインモデルを公開してはいけない。 多数のモデルがあることの問題は、それらがデータしか含んでいないことだ。ここには振る舞いがまったく欠けている、いわゆる貧血症のモデルだ。こうしたモデルを公開すると、リソースをCRUD (Create, Read, Update, Delete) することになる。これは必ずしも悪いことではなく、純粋なCRUD APIが必要な場合もある。CRUDモデルを公開することの問題は、どのリソースでどんなアクションが実行できるのか、どんな順番で実行するのかなど、APIを利用するクライアント側に多数の知識が必要になることだ。大量のロジックをクライアント側に実装することになり、クライアントとサーバが密結合してしまう。
目的をはっきりさせてからAPIを設計しよう。クライアントが何をしたいのか、どのようにやりたいのか考えよう。「どれだけ明確でシンプルであるべきか」対「どれだけ柔軟性が必要か」、明確さと柔軟さのトレードオフが必要になるときもある。「最も利益を生む顧客」の情報を取得したい場合、柔軟性はあるが、より指示的な方法は以下になる。
GET /customers?sortBy=grossmargin&order=descending
これに対して、もっと宣言的なスタイルにすることもできる。この方が目的ははっきりするが、柔軟性には欠ける。
GET /most_profitable_customers
Oliver氏がここで言いたいことは、何のためにクライアントがAPIを使うのか、その目的をよく考え、APIをその要求に合わせよう、ということだ。
GETとPOSTを乱用してはいけない。ここで言っているのは、使い方を間違えて、HTTP仕様に違反してはいけない、ということだ。たとえば、リソースを削除するのにGETやPOSTを使ってはいけない。HTTP動詞は理由があって定義されており、互いに補い合っている。仕様に従うことで、さまざまなメリットがある。HTTP動詞を適切に使うことで、クライアントが何をしたいのか、クライアントはサーバからどんな振る舞いを期待できるのかが明らかになる。
エラーコードの選択肢を200と500に限定してはいけない。すべてのエラーコードを使いこなそう。エラーコードには160もの選択肢があり、考え得るほとんどすべてのエラータイプが用意されている。適切なエラーコードを使うことは、クライアントが適切にエラーハンドリングするのに重要だ。よく見かけるのは、エラーが発生しているにもかかわらず、サーバが200, OKを返すことだ。実際にはうまくいっていないのに万事順調なふりをすることが良い考えになることはめったにない。
キャッシュを無視してはいけない。どんなに厄介者になることがあろうとも、キャッシュはWebの重要なパーツだ。適切なキャッシュヘッダを追加することで、キャッシュを活用しよう。たとえば、もしキャッシュしてほしくなければ、そのことを明示してキャッシュしないようにしよう。キャッシュをうまくコントロールする方法の1つは、バリデータ、できればEtagを使うことだ。これによりサーバ側はデータに基づいて振る舞えるようになる。Etagはサーバ側で生成してキャシュに渡す値であり、リソースが最新かどうかをサーバに問い合わせるのに使われる。
バージョニングを要求してはいけない。リソース上の変更だと思っても、実際には表現上の変更にすぎないことが多い。それは同じリソースであり、同じURLであるべきだ。したがって、URLにバージョンを付けるのは避けよう。代わりに、メディアタイプにv2を追加するなどするべきだ。
Content-Type=application/vnd.company.v2+xml
コンテントネゴシエーションの拡張を使ってはいけない。表現フォーマットをネゴシエーションする適切な方法は、ヘッダのAcceptとContent-Typeを使うことだ。
GOTO Berlin Conference 2013は、ベルリンで初めて開催されるGOTOカンファレンスであり、約420名の出席者と80名の講演者が参加する。