REST APIの始め方 (主要なHTTPメソッド)

Tuyoshi Akiyama
Aug 25, 2017 · 6 min read

前回の続きになります。今回は、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/sample

GETは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_stuff

PUTは、ソースの更新処理に使われます。新しく更新された、ソースを表すデータを含んだリクエストを、既知のソースの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/orders

POSTは、新しいリソースの作成に利用します。 例えば、新しいリソースを作成する際、親(上の例でいう、一つ目のリンク)に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/sample

DELETEは成功すると、response body、削除された項目、またはラップされたレスポンスと一緒に200(OK)コードを返します。(Bodyがない場合は204コードです。)

また、DELETE操作はぺき等です。これは、DELETEがソースに修正を加える一方で、そのべき等性を保つことが求められることを意味します。

例えば、DELETE操作を2回、あるソースに行います。 2回目のリソースに対してDELETEを呼び出すと、すでに削除されてもはや見つけられないため、404(NOT FOUND)が返されます。この場合、DELETE操作はもはや冪等とはいえません(

削除フラグではなく、データベースからリソースが削除された場合には、適切な妥協策となります)。


以上が、主な4つのHTTPメソッドになります。

次回は、リソースの名前をつける際のベスト・プラクティスについて見ていきます。

)
Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade