第2回 RESTfulなAPIの設計を学ぼう：連載：ASP.NET Web API 入門（2/2 ページ）

Web APIといっても、どのようなURLの、どのようなAPIを定義すればよいのか？ RESTfulなHTTPサービスを実装するためのAPIの定義方法の基礎を説明する。

[矢後比呂加，著] PC用表示関連情報

LINE

Hatena

前のページへ | 　　　　　　

1. RESTfulなAPIの設計を学ぼう

　ここではRESTfulなAPIを設計するために、最低限押さえておきたい3つのポイントを紹介する。

HTTPメソッドは、リソース*5をどのように操作したいかを表す
URLはリソースの名前を表す
APIの処理の結果は、ステータス・コードで表す

　RESTfulなAPIを設計することは、ASP.NET Web APIでは重要だ。それぞれのポイントについて解説する前に、「RESTfulとは何か」「RESTfulとASP.NET Web APIはどのような関係であるか」について、簡単に整理しておこう。

*5　リソースとは、Web上に存在する「情報」のことである。ショッピングサイトのアプリケーションを例に言えば、「顧客」「注文」「商品」「商品カテゴリ」などがリソースに値する。

1-1 RESTfulとは

　「RESTfulな○○」という言葉は、「RESTの制約に従っている○○」という意味を表す。RESTとは、アーキテクチャ・スタイルの一種で、「制約の集まり」と考えてよいだろう。何を制約するか？それは狭義では「どのようにHTTP通信を利用するか」を制約する。HTTPメッセージにはどのような情報を格納するか、どのようにHTTPメソッドやHTTPヘッダを指定するか、などといった制約の集まりがRESTである*6。

*6　RESTの出典は、Roy Fielding氏の博士論文であり、2000年に登場してから今日に至るまでさまざまな解釈が存在する。本稿で扱うRESTは、Web APIに適用されるものに限定している。

　ASP.NET Web APIは、RESTfulなHTTPサービスを提供することに特化したフレームワークであるというだけで、必ずしもRESTfulな実装を行うべきというわけではない。RESTfulではない実装ももちろん行うことができる（むしろ実際の開発現場では、部分的にRESTfulな実装を選択しないケースも少なくはないだろう）。

　だが、特に理由のない場合は、RESTのアーキテクチャ・スタイルに従う方がよいだろう。RESTには、いくつかのポイントが存在するが、その中でも今回は、ASP.NET Web APIでの実装の根幹に関わる部分として、先述の3つのポイントを解説する。それでは、1つ目から見ていこう。

1-2 HTTPメソッドは「リソースをどのように操作したいか」を表す

　1つ目のポイントは、HTTPメソッドの選択である。HTTPメソッドは、リソースをどのように操作したいかにより選択する。どのようなときに選択するべきか、HTTP1.1の仕様で定義されている8つのHTTPメソッドのうち、主要な4つについて、以下の表にまとめた。


HTTPメソッド	リソースの操作
GET	リソースを取得する
POST	リソースを新たに追加する
PUT	リソースを更新する
DELETE	リソースを削除する
表1　主要なHTTPメソッドと、対応するリソースの操作

　例として、前掲の顧客APIが選択しているHTTPメソッドを見てみよう（下の表2）。表1のとおりにHTTPメソッドが選択されていることが確認できる。


顧客APIの処理内容	選択されているHTTPメソッド
顧客データを全て取得する	GET
Idと一致する顧客データを取得する	GET
Idと一致する顧客データを更新する	PUT
顧客データを追加する	POST
Idと一致する顧客データを削除する	DELETE
表2　顧客APIの処理内容と、選択されているHTTPメソッド

1-3 URLはリソースの名前を表す

　2つ目のポイントは、URLの決定の仕方である。URLは、APIの処理の対象となるリソースの名前を表すようにする。再び、顧客APIの例を見てみよう。顧客APIの処理内容と、対象となるリソース、定義されているURLを下の表3にまとめた。


顧客APIの処理内容	対象となるリソース	定義されているURL
顧客データを全て取得する	顧客全体	~/api/customers
Idと一致する顧客データを取得する	Idと一致する顧客	~/api/customers/{id} ……（1）
Idと一致する顧客データを更新する	Idと一致する顧客	~/api/customers/{id}
顧客データを追加する	顧客全体	~/api/customers
Idと一致する顧客データを削除する	Idと一致する顧客	~/api/customers/{id}

表3　顧客APIの処理内容と、選択されているHTTPメソッド
（1）の「{id}」には任意のId値が入る。

　顧客APIでは、5つのAPIが定義されているが、表3を確認すると、URLは以下の2種類のみ定義されていることが分かる。

~/api/customers
~/api/customers/{id}

　リソースの名前をURLで表すことで、URLに一貫性が生まれていることがよく分かる。

　また、先述の1つ目のポイントとまとめると、とあるコツが見えてくる。それは、HTTPメソッドは動詞、URLは名詞と見なすことだ。（例：全ての顧客［~/api/customers］を取得［GET］する）もし、名詞と動詞に当てはまらない情報を表す必要がある場合は、クエリ文字列やBody、ヘッダなどで表すとよいだろう*7。

*7　よくある問題として、POSTとPUTの使い分けが分からないといったことがある。その場合は、クライアント側でURLを指定できるかどうか、を判断基準にするとよいだろう。クライアント側でURLが決められる場合（対象のリソースをURLで表せる場合）は、PUTを選択し、そうでなければPOSTを選択する。

1-4 APIの処理の結果は、ステータス・コードで表す

　最後である3つ目のポイントは、HTTPレスポンスに関する部分だ。サーバ側で行うAPIの処理の結果は、HTTPレスポンスのステータス・コードで表す。

　例として、顧客APIで返される可能性があるHTTPレスポンスのステータス・コードを、下の表4にまとめた。1つのAPIでも、処理の結果に応じて、さまざまなステータス・コードが選択されていることを確認してほしい。


APIの処理の結果	返されるHTTPレスポンス
	ステータス・コード	Body
顧客データの取得・削除に成功した場合	200 OK	対象となる顧客データが格納される
顧客データの追加に成功した場合	201 Created	追加した顧客データが格納される（ヘッダのLocationには、追加した顧客データを表すURLが格納される）
顧客データの更新に成功した場合	200 OK	空
顧客データが存在しない場合	404 Not Found	空
リクエストに検証エラーが存在する場合	400 Bad Request	検証エラー情報が格納される
データベース更新時に同時実行制御のエラーが発生した場合	404 Not Found	エラー情報が格納される
メソッド内で例外が発生した場合	500 Internal Server Error	エラー情報が格納される
表4　顧客APIにおける、処理の結果とHTTPレスポンス

　ステータス・コードは大まかに分けて5つ（1xx系情報／2xx系成功／3xx系リダイレクション／4xx系クライアント・エラー／5xx系サーバ・エラー）に分けられ、さまざまな結果を表すステータス・コードが用意されている。HTTPレスポンスの内容を検討する際はぜひ、ステータス・コードの一覧（参考：HTTPステータス・コード - Wikipedia）を確認してから、適切な値を選択することを推奨する。

　よく使用されるステータス・コードとその意味を下の表5にまとめたので、参考にしてほしい。


	分類	ステータス・コード	意味
	2xx系	200 OK	リクエストが成功し、要求に応じてリソースがBodyに格納される
		201 Created	リソースの作成に成功したことを表す。新しいURLは、ヘッダ「Location」に入る
		204 No Content	リクエストが成功したが、返すべきリソースが存在しないことを表す
	3xx系	301 Moved Permanently	リソースが恒久的に移動していることを表す
	4xx系	400 Bad Request	リクエストが不正であることを表す
	4xx系	401 Unauthorized	認証が必要であることを表す
	5xx系	500 Internal Server Error	サーバ内部でエラーが発生したことを表す
表5　よく使用されるステータス・コードとその意味

　RESTfulなAPIを設計するための3つのポイントについて解説は以上だ。これらは全てHTTPに関わる内容であったが、次回は、フレームワークであるASP.NET Web APIの世界に戻ろう。

　APIコントローラの実装方法について解説していくが、今回紹介した3つのポイントを容易に実装できるようになっている点にも注目してみてほしい。

「連載：ASP.NET Web API 入門」