BT

GOTO Berlin: Web APIでやっていいこと、いけないこと

| 作者: Jan Stenberg フォローする 29 人のフォロワー , 翻訳者 笹井 崇司 フォローする 0 人のフォロワー 投稿日 2013年10月27日. 推定読書時間: 4 分 |

原文(投稿日:2013/10/19)へのリンク

メーリングリストやフォーラムでは、RESTWeb 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名の講演者が参加する。

この記事に星をつける

おすすめ度
スタイル

こんにちは

コメントするには InfoQアカウントの登録 または が必要です。InfoQ に登録するとさまざまなことができます。

アカウント登録をしてInfoQをお楽しみください。

あなたの意見をお聞かせください。

HTML: a,b,br,blockquote,i,li,pre,u,ul,p

このスレッドのメッセージについてEmailでリプライする
コミュニティコメント

HTML: a,b,br,blockquote,i,li,pre,u,ul,p

このスレッドのメッセージについてEmailでリプライする

HTML: a,b,br,blockquote,i,li,pre,u,ul,p

このスレッドのメッセージについてEmailでリプライする

ディスカッション

InfoQにログインし新機能を利用する


パスワードを忘れた方はこちらへ

Follow

お気に入りのトピックや著者をフォローする

業界やサイト内で一番重要な見出しを閲覧する

Like

より多いシグナル、より少ないノイズ

お気に入りのトピックと著者を選択して自分のフィードを作る

Notifications

最新情報をすぐ手に入れるようにしよう

通知設定をして、お気に入りコンテンツを見逃さないようにしよう!

BT