REST APIの始め方 (名前の付け方)
前回はHTTPメソッドについて、まとめました。今回は、そのメソッドを活用していく為にも、リソースのネーミングについて確認していきます。
REST APIでは、名前はとても重要な役割を担います。
そもそも、APIはシンプルなURIの集まりといえ、それぞれのリソースは独自のURL、またはアドレスを持ちます。これら、URIとHTTPメソッドとが一緒になって、リソースはアクセス可能になります。
では、まず前提として、URIをは名詞で表されたリソースを参照するようにします。つまりは、URIの名前つけの際には、名詞が使われます。
実際に、次の例をみていきます。
ある顧客データに、新しいデータを追加する時、次のように表されます。
POST http://www.example.com/customersまた、GET/PUT/DELETE処理を行う場合は、
GET http://www.example.com/customers/33245上のように、costomerのID33245に対して行われる処理であることが分かります。
ある商品に対しても、同様になります。
POST http://www.example.com/productsGET|PUT|DELETE http://www.example.com/products/66432
上のPOSTは、ある商品に対して、新しいデータを追加する処理です。
これが、あるcustomerの注文(新規オーダー)に対しての場合、次のURIがより分かりやすいものとなります。
POST http://www.example.com/customers/33245/ordersまた、次の3つのURIを見ていき、URIにおける階層の意味を理解します。
POST http://www.example.com/customers/33245/orders/8769/lineitemsPOST www.example.com/orders/8769/lineitems URIGET http://www.example.com/orders/8769
それぞれは、
- customer番号ID33245のお客さんが複数のアイテム(lineitems)を新規注文(POST)し、そのオーダー番号8769となる
- オーダー番号8769のlineitemsに対して、新規注文を行う。customer番号がなくても、オーダー番号だけでlineitemsが意味を成す場合に使われる。
- お客さん情報を得ることなく、そのオーダー(番号8769)そのものをGETする。
となります。また、例えば複数の商品(lineitmes)の、一つ目の商品情報をみるURIは次のようになります。
GET http://www.example.com/customers/33245/orders/8769/lineitems/1APIの例として、次のものが挙げられています。
では、ネーミングにおけるアンチパターンについて見ていきます。
サービス上、要求された操作やHTTP動詞を指定するために、クエリ文字列パラメータを使用して、サービスインターフェイスを指定するURIを使用することがよくあります。
たとえばID 12345の顧客を更新する場合、JSON本体のリクエストは次のようになります。(この例はアンチパターンで、やってはいけないものです)
GET http://api.example.com/services?op=update_customer&id=12345&format=jsonこの例では、更新作業を行っていながら、GETメソッドが使われています。本来は、ここにはPUT(更新)が代わりに用いられます。
更に、 op=update_customer のようなURI内に、その処理内容をきじゅつするものがあります。処理動作はHTTPメソッドで行い、URIには名詞が本来使われるものです。
つまり、まとめると
- 処理内容とHTTPメソッド名が矛盾してはいけません
- URIに動詞(処理内容)の記述があると、そのAPIの意図を不明瞭にします。基本は、名詞のみが用いられます。
となります。
また一般的に、ノード名に複数形を使用し、すべてのAPI URIの一貫性を保たれるのがベスト・プラクティスとなります。
次の例を見ていきます。
GET http://www.example.com/customers/33245/orders/8769/lineitems/1ここでの、「customers」、「orders」、および「lineitems」URIノードはすべて複数形です。
これは、実際には各ルートリソースに2つの基本URLしか必要ないことを意味します。 1つはコレクション内のリソースの作成用で、もう1つはその識別子によるリソースの読み取り、更新、および削除用です。つまり、POSTとPUT/DELETE/GET用の2つが、最小限のURIの数になります。
顧客ごとに設定が1つしかなかったとすると、URLは次のようになります。
GET | PUT | DELETE http://www.example.com/customers/12345/configurationここでは、単数形が用いられます。
その意味に合わせての使い分けが必要ですが、基本的には複数形の名詞を用いて、名前が付けられます。
以上がネーミングのルールになります。
次は、HTTPリクエストを受けた際の、返すデータにつてい見ていきます。
