REST APIの始め方 (主要なHTTPメソッド)
前回の続きになります。今回は、HTTPリクエストで使われるメソッドの定義を、まとめていきます。
前回の記事に出てきた、uninform interface(均一)ルールの中で、ソースは名詞であることが定義されていましたね。そのソースに対して、どのような処理を加える(動詞)かが、HTTP Verbsとなります。
今回は、以下の(CRUD = create, read, update, delete)メソッドの定義の説明になります。他にもメソッドはありますが(OPTIONやHEAD等)、主に使われるメソッドは次のものになっています。
- POST
- GET
- PUT
- DELETE
では、それぞれの定義を見ていきましょう。
GET
まず、次のGETの使用例を見ていきます。
GET http://www.example.com/customers/12345
GET http://www.example.com/customers/12345/orders
GET http://www.example.com/buckets/sampleGETはXMLまたはJSONデータとHTTP応答コード200(OK)を返します。この2つが返っていれば、パスが正しく、エラーも無いと云うことです。
エラーの場合、大抵は、404(NOT FOUND)または400(BAD REQUEST)コードが返されます。
またGETメソッドは、安全性とべき等を持つものと云えます。
複数のリクエストは一つのリクエストして、同じ結果が返ってきます。また、ソースの変更などをGETで行うなどは、しない設計が求められます。
PUT
例:
PUT http://www.example.com/customers/12345
PUT http://www.example.com/customers/12345/orders/98765
PUT http://www.example.com/buckets/secret_stuffPUTは、ソースの更新処理に使われます。新しく更新された、ソースを表すデータを含んだリクエストを、既知のソースのURIに送信します。
更新が成功した場合、200(本文がコンテンツを返さない場合、204)を、それがcreate処理の場合、201を返します。
clientはすでにリソースIDを特定しているため、PUTが作成機能を担う場合、Locationヘッダー経由でリンクを返す必要はありません。
また、PUTはサーバー上で状態を変更するという点で、安全とは言えませんが、それは冪等です。つまり、PUTを使用してリソースを更新してから、同じ呼び出しをもう一度行うと、リソースは最初の呼び出し時と同じ状態で存在します。
また、PUTの使用には、一つ注意点があります。
それは、リソースIDがserverではなく、clientによって選択される場合です。この場合、PUT経由でソースが新しく作成されることが起こり、操作の複雑性を増します。この場合は、代わりにPOSTを使用して新しいリソースを作成し、Bodyの表現にクライアント定義のIDを提供することが望ましい方法になります。
つまり、存在しないURIへは、PUTではなくPOSTを使って作成することがベスト・プラクティスになります。
POST
例:
POST http://www.example.com/customers
POST http://www.example.com/customers/12345/ordersPOSTは、新しいリソースの作成に利用します。 例えば、新しいリソースを作成する際、親(上の例でいう、一つ目のリンク)にPOSTを送ると、サービスは親と新しいリソースを関連付け、ID(新しいリソースURI)の割り当て(上の例の二つ目のリンク)を行います。
作成に成功すると、HTTPステータス201が返され、新しく作成された201 コードのリソースへの、リンク付きのLocationヘッダーが返されます。
POSTは安全でなく、冪等でない方法です。 非冪等のリソース要求に対して、PUTが使用されます。
例えば、2つの同一のPOSTリクエストを作成します。すると、同じデータを含んだ、2つのリソースが作成される場合が多いです。
また先程にもあった、PUTとPOSTの使い分けについてです。
例えば、serverが作成する前に、結果として得られるURIが何であるかを知っていない(またはそうすべきではない)場合は、POSTを使用して新しいリソースを作成することが推奨されています。
DELETE
例:
DELETE http://www.example.com/customers/12345
DELETE http://www.example.com/customers/12345/orders
DELETE http://www.example.com/buckets/sampleDELETEは成功すると、response body、削除された項目、またはラップされたレスポンスと一緒に200(OK)コードを返します。(Bodyがない場合は204コードです。)
また、DELETE操作はぺき等です。これは、DELETEがソースに修正を加える一方で、そのべき等性を保つことが求められることを意味します。
例えば、DELETE操作を2回、あるソースに行います。 2回目のリソースに対してDELETEを呼び出すと、すでに削除されてもはや見つけられないため、404(NOT FOUND)が返されます。この場合、DELETE操作はもはや冪等とはいえません(
削除フラグではなく、データベースからリソースが削除された場合には、適切な妥協策となります)。
以上が、主な4つのHTTPメソッドになります。
次回は、リソースの名前をつける際のベスト・プラクティスについて見ていきます。
