RESTful HTTPサービス開発を実践!ASP.NET Web API徹底解剖

この記事を読むのに必要な時間:およそ 3 分

自由自在にURLを定義する

URLルーティング機能より,URLとエンドポイントのマッピングを設定することができるため,URLを自由自在に定義することもできます。

リスト5のコードは,URL「api/customer/{groupName}/{id}」を,CustomerクラスのGetByGroupNameメソッドにマッピングを行う例です。

リスト5 URLルーティングの例

config.Routes.MapHttpRoute(
    name: "GetCustomerApi",
    routeTemplate: "api/customer/{groupName}/{id}",
    defaults: new { 
        controller = "Customer", 
        action = "GetByGroupName" },
    constraints: new { 
        httpMethod = new HttpMethodConstraint(HttpMethod.Get) }
);

URLだけなく,HTTPメソッドの条件も指定することができます。

またこのURLルーティングでは,マッピングを設定するだけではなく,{groupName}や{id}の様に,URLの一部をパラメータとして定義し,エンドポイントにてその値を受け取ることもできます。

ODataのURL規約によるクエリオプションの利用

ASP.NET Web APIはODataにも対応しました。それに伴い,ODataのURL規約によるクエリオプションを利用できます。

URLに「$top=2」「$orderby=name」と付けることで,コレクションの値をどのように取得するかクライアント側で指定することができます。

実装は,リスト6のようにエンドポイントのメソッドにQueryable属性をつけるだけです。

リスト6 Queryable属性の付与

// GET api/customer
[Queryable]
public IEnumerable<Customer> GetAll()

この例では,⁠api/customer?$top=2&$skip=1」というURLでクエリオプションを指定した場合,コレクションを1つスキップし,上位2つのCustomerの値が返されます。

また,このクエリオプションの利用に制限を加えることもできます。

$skipの利用は制限したい,といった場合は,以下の様に属性のプロパティを設定します。クライアントが$skipをURLに追加して送信すると,エラーメッセージを含んだレスポンスが返されます。

リスト7 クエリオプションを制限する

// GET api/customer
[Queryable(AllowedQueryOptions = AllowedQueryOptions.Skip)]
public IEnumerable<Customer> GetAll()

このようにODataクエリオプションに対応したことにより,データベースから値を必要な範囲だけ取得するといったことや,ページングの処理等を,容易に行えるようになりました。

さまざまなメディアタイプへの対応

冒頭のエンドポイントのコードでは,リクエストとレスポンスを共にCustomerオブジェクトで定義しましたが,実際のHTTP通信では,さまざまなメディアタイプ(JsonやXML等)が利用されます。

ASP.NET Web APIは,クライアントから要求されるメディアタイプに対応できるよう,拡張ポイントが用意されています。デフォルトでは,application/json,application/xml,application/x-www-form-urlencodedの3つに対応しているので,それら以外に対応する必要がない場合は特に手を加える必要はありません。

もしimage/jpgやmultipart/form-data等他のメディアタイプに対応する場合は,⁠MediaTypeFormatter」を実装することになります。

ここでは実装方法を割愛しますが,冒頭のエンドポイントのコードを例に,概念図を図2に掲載します。

図2 MediaTypeFormatterの概念図

図2 MediaTypeFormatterの概念図

たとえば,メディアタイプtext/plainに対応する場合は,Customerオブジェクトをtext/plainにシリアライズ・シリアル化解除する処理を,MediaTypeFormatterに記述することになります。

このとき,エンドポイントのコードを変更する必要はありません。対応するメディアタイプが増えた場合でも,エンドポイントとは疎結合に拡張することができます。

強力な開発者へのサポート機能

最後にコードから少し離れて,開発を支援する強力な機能をご紹介します。

ヘルプページ自動生成機能と,トレース機能です。

前者の機能は,コードから自動的にAPIのヘルプページを生成する機能です図3⁠。

図3 自動生成されたヘルプページの例

図3 自動生成されたヘルプページの例

このヘルプページはASP.NET MVCで作成され,そのままWebサイトとして発行することができます。また,CSSとHtmlはプロジェクトに配置されているため,構成やデザインは自由に変更することができます。

後者のトレース機能は,フレームワーク内部の働きをログとして出力してくれる機能です図4⁠。実装の問題発見に役に立つでしょう。

図4 トレースの出力結果

図4 トレースの出力結果

以上,ASP.NET Web APIの特徴をご紹介させて頂きました。

ASP.NET Web APIのライブラリはNuGetで配布されており,Visual Studioにはテンプレートが用意されています。ご興味をお持ちになった方はぜひお試しになってはいかがでしょうか。

著者プロフィール

矢後比呂加(やごひろか)

ASP.NETをベースにした開発を行なう,Webシステム開発エンジニア。

趣味はピアノ。