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

» 2013年10月23日 13時34分 公開
[矢後比呂加,]
前のページへ 1|2       

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 リクエストが不正であることを表す
401 Unauthorized 認証が必要であることを表す
5xx系 500 Internal Server Error サーバ内部でエラーが発生したことを表す
表5 よく使用されるステータス・コードとその意味


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

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

「連載:ASP.NET Web API 入門」のインデックス

連載:ASP.NET Web API 入門

前のページへ 1|2       

Copyright© Digital Advantage Corp. All Rights Reserved.

スポンサーからのお知らせPR

注目のテーマ

Microsoft & Windows最前線2025
AI for エンジニアリング
ローコード/ノーコード セントラル by @IT - ITエンジニアがビジネスの中心で活躍する組織へ
Cloud Native Central by @IT - スケーラブルな能力を組織に
システム開発ノウハウ 【発注ナビ】PR
あなたにおすすめの記事PR

RSSについて

アイティメディアIDについて

メールマガジン登録

@ITのメールマガジンは、 もちろん、すべて無料です。ぜひメールマガジンをご購読ください。