第3回 APIコントローラの実装方法：連載：ASP.NET Web API 入門（1/3 ページ）

連載目次

　前回に引き続き、「APIコントローラの実装」について解説を行う*1。今回は、より実践的なAPIコントローラの実装方法を学ぶ。前回、RESTfulなAPIを設計するための3つのポイントを説明したが、それらが容易に実装できるようになっている点にも注目してみてほしい。

　前回〜今回の目次（再掲）は、以下のとおりだ。

【前回】
　 1. RESTfulなAPIの設計を学ぼう
　　 1-1. REST とは
　　 1-2. HTTPメソッドは、リソースをどのように操作したいかを表す
　　 1-3. URLはリソースの名前を表す
　　 1-4. APIの処理の結果は、ステータス・コードで表す

【今回】
　 2. APIコントローラの実装
　　 2-1. APIコントローラの役割とは
　　 2-2. APIコントローラの用意
　　 2-3. HTTPリクエストを取得する
　　 2-4. HTTPレスポンスの内容を指定する

　なお、開発環境はMicrosoft Visual Studio Express 2012 for Web（Update3）、言語はC#、対象とするASP.NET Web APIのバージョンは1とする*2。

　今回、実装するAPIコントローラのコード内容や仕様は、前回の「今回〜次回で使用するAPIコントローラのサンプル・コード」で説明しているので、こちらをもう一度ざっと眺めていただくことでより全体が理解しやすくなるだろう。

2. APIコントローラの実装

　ここでは、APIコントローラの実装方法について解説する。大半のケースでは、APIコントローラはリソースごとに作成し、

• HTTPリクエストの取得
• 処理の実行
• HTTPレスポンスの決定

と主に3つの処理を記述することになる。

　詳しい実装方法に入る前に、まずはASP.NET Web APIにおけるAPIコントローラの役割を明確にしよう。

2-1 APIコントローラの役割とは

　ASP.NET Web APIフレームワークの全体の流れ（クライアントからHTTPリクエストを受けて、HTTPレスポンスを返すまでの一連の流れ）を、APIコントローラを中心に下の図2にまとめた。

図2　ASP.NET Web APIフレームワークの流れ
ASP.NET Web APIフレームワークの流れを、APIコントローラを中心に表した図。
本稿は、（2）のAPIコントローラを対象としている。（1）のルーティングの設定は、第4回目で解説予定。（3）の部分は、今回は特に意識する必要はない。

　流れを順に追っていくと、以下のとおりとなる。

　（1）ASP.NET Web APIフレームワークは、HTTPリクエストを受けて、ルーティングの設定を参照し、APIコントローラ・クラスとそのメソッドを特定して呼び出す ……（1）
　（2）呼び出されたAPIコントローラ・クラスのメソッドは、HTTPリクエストの値を参照し、APIの目的である処理を実行した後、クライアントへ返すためのHTTPレスポンスの内容を決定する ……（2）
　（3）ASP.NET Web APIフレームワーク（APIコントローラ以外の部分）は、HTTPレスポンスを構築し、クライアントへ返す ……（3）

　つまりAPIコントローラの役割は、APIの目的である処理を実行し、HTTPレスポンスの内容を指定することにある。この役割を踏まえ、開発者は主に3つの処理をAPIコントローラに記述する。

• a. 処理を実行するために必要なHTTPリクエストの値を取得する
• b. 処理を記述する
• c. HTTPレスポンスの内容を指定する

　大半は、aはメソッドの引数、bはメソッド内、cはメソッドの戻り値にて表す。例として、前回のリスト1「顧客APIコントローラ・クラス」のコードの中で該当する箇所を下の図3に示す。

図3　APIコントローラ・クラスのメソッドにおける仕事

　bの処理の記述は、データベースへの登録などのアプリケーション固有の処理なので、本連載では説明を省略する。まずは、APIコントローラの用意について、それから、aのHTTPリクエストを取得する方法と、bのHTTPレスポンスの指定方法について解説する。この部分は本連載の要となる。

2-2 APIコントローラの用意

　APIコントローラの用意は、Visual Studio 2012（または、Visual Studio Express 2012 for Web）のウィザード機能を利用することで容易に作成できる。

　第1回と同様、ASP.NET Web APIのプロジェクトを用意し、ソリューション・エクスプローラから「Controllers」フォルダを右クリックし、表示されたコンテキスト・メニューから［追加］−［コントローラー］を選択する。表示される［コントローラーの追加］ダイアログ（図4）にて、［コントローラー名］にAPIコントローラ・クラスの名前（今回は「CustomersController」）を、［テンプレート］は「空のAPIコントローラー」を選択し、［追加］ボタンをクリックする。

図4　［コントローラの追加］ダイアログ

　第1回の「APIコントローラ」でも簡単に触れたが、APIコントローラとなるクラス（以降、APIコントローラ・クラスと呼称）の条件は、以下のとおりだ。

• ApiControllerクラス（System.Web.Http名前空間）を継承する*8
• クラス名のサフィックスを「Controller」にする

　プロジェクト内におけるAPIコントローラ・クラスの配置先（名前空間）はどこでもよいが、ASP.NET Web APIのプロジェクト・テンプレートに合わせて「Controllers」フォルダに配置することを推奨する。

　APIコントローラ・クラスはリソース単位に作成し、クラス名は「リソース名＋Controller」とするのがよいだろう。例えばリソースが「顧客」であれば「CustomersController」、「注文」であれば「OrdersController」になる。そうすれば、デフォルトのルーティングの設定*9により、「~/api/customers/」や「~/api/orders/」から始まるURLでAPIを定義できる。

○ メソッドを用意する

　APIを定義するには、APIコントローラ・クラスにメソッドを追加する必要がある（このAPIの定義となるメソッドのことを、アクション・メソッドと呼称する）。アクション・メソッドの名前の付け方には規約があり、HTTPリクエストのHTTPメソッドで始める（例：HTTPメソッドが「GET」であれば、アクション・メソッドの名前を「GetCustomers」にする）。アクション・メソッドの引数や戻り値は、次の章のHTTPリクエストの取得とHTTPレスポンスの内容の指定にて解説を行う。