REST APIの始め方 (名前の付け方)

Tuyoshi Akiyama
Aug 26, 2017 · 5 min read

前回は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/1

APIの例として、次のものが挙げられています。


では、ネーミングにおけるアンチパターンについて見ていきます。

サービス上、要求された操作や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リクエストを受けた際の、返すデータにつてい見ていきます。

)
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