Skip to content

MS_ASPNETWebAPI

Jump to bottom
nishi_74322014 edited this page Aug 3, 2026 · 1 revision

ASP.NET Web API

概要

  • RESTful な HTTP サービスを構築するためのフレームワーク。
  • 軽量のため、ASP.NET MVC（MS_ASPNETMVC.md）と違い、専門書などは不要。

補足（最新化）: 本ページは ASP.NET Web API 2（.NET Framework、 System.Web.Http 名前空間）についての内容である。 ASP.NET Core では MVC と Web API が統合され、 ControllerBase を継承した 1 つのパイプラインに一本化された。 名前空間・型名が変わっているため、 本ページのコードをそのまま ASP.NET Core に持ち込むことはできない。

ASP.NET Web API 2 ASP.NET Core
System.Web.Http Microsoft.AspNetCore.Mvc
ApiController ControllerBase + [ApiController]
HttpConfiguration / WebApiConfig Program.cs（builder / ミドルウェア）
config.Routes.MapHttpRoute MapControllers / Minimal API
System.Web.Http.Filters.ActionFilterAttribute Microsoft.AspNetCore.Mvc.Filters.ActionFilterAttribute

基本

ルーティング

  • WebApiConfig で一括定義する。
  • Attribute を付与して個別定義する。

参考: 【ASP.NET】APIのルーティングを設定する2つの方法【WebAPI】 - ばしぶろ

JSON

以下が参考になる。

  • JSONを送信するRESTサービスを作成する方法（MS_JSONRestService.md）
  • JSONを受信するJSON-RPCサービスを作成する方法（MS_JSONRPCService.md）

認証

OAuth 2.0、OpenID Connectを使用する。

以下が参考になる。

  • WebAPIの認証
  • ASP.NET IdentityのOAuth2によるSTS実装（MS_ASPNETIdentitySTSOAuth2.md）

リクエスト送信方法

以下が参考になる。

WebApiConfigの例

/// <summary>MultiPurposeAuthSite.App_Start</summary>
namespace MultiPurposeAuthSite.App_Start
{
    /// <summary>WebApi定義（テンプレート）</summary>
    public static class WebApiConfig
    {
        /// <summary>Register</summary>
        /// <param name="config">HttpConfiguration</param>
        public static void Register(HttpConfiguration config)
        {
            // Web API configuration and services
            // 「Bearer Token」認証のみを使用するように、Web API を設定。
            config.SuppressDefaultHostAuthentication();
            config.Filters.Add(new HostAuthenticationFilter(OAuthDefaults.AuthenticationType));

            // JSON データにはCamelCaseを使用 (JSON.NET)
            config.Formatters.JsonFormatter.SerializerSettings.ContractResolver
                = new CamelCasePropertyNamesContractResolver();

            // CORS (Cross-Origin Resource Sharing)の有効化
            // 別ドメイン上で動作する Web アプリからアクセス可能に設定。
            config.EnableCors();

            // Web API routes を設定する。

            // Attribute Routing
            config.MapHttpAttributeRoutes();

            // MapHttpRoute
            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{action}/{id}",
                defaults: new { id = RouteParameter.Optional }
            );
        }
    }
}

Routing

MapHttpRoute

  • 既定では、以下のように Routing が定義されている。

    config.Routes.MapHttpRoute(
    name: "DefaultApi",
    routeTemplate: "api/{controller}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

  • ASP.NET MVC と違い、ASP.NET Web API の Route 定義には、
    （既定では）Action Method 名の指定が無い。

  • 代わりに、Web API を使用した場合、リクエストの HTTP メソッドに応じて、
    以下のように Controller の Action Method が自動的に呼び出される。

項番 HTTP メソッド 呼び出されるメソッド
１ GET "Get" で始まる名前のメソッド
２ POST "Post" で始まる名前のメソッド
３ PUT "Put" で始まる名前のメソッド
４ DELETE "Delete" で始まる名前のメソッド

  • 従って、Web API の Action Method を呼び出す際の URL は、
    HTTP メソッドを加味し、以下のようになる。

    http://ip or fqdn(:port)/(application名/)Controller名/id

  • {id} は URL から引数を取る方法で、
    （Optional に設定しているため、）使用しても、しなくても OK。

  • 上記の定義の場合、WebAPI のクラス・メソッド定義は、以下のようになる。

    public class ValuesController
{
    // GET ~/api/values/?id=32
    public string Get(int id)
    {

  • また、デフォルトの HTTP メソッドに対応した ActionMethod を使用するのではなく、
    以下の様に {action} の定義を行えば、独自の ActionMethod 名を明示できる。

    config.Routes.MapHttpRoute(
    name: "DefaultApi",
    routeTemplate: "api/{controller}/{action}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

  • 従って、Web API の Action Method を呼び出す際の URL は以下のようになる。

    http://ip or fqdn(:port)/(application名/)Controller名/ActionMethod名/id

MapHttpAttributeRoutes

補足: ASP.NET Core では、上記 2 方式のうち 属性ルーティングが標準である （[Route("api/[controller]")] + [HttpGet("{id}")]）。 「HTTP メソッド名で始まるメソッド名から自動的に決まる」という 規約ベースのルーティングは無くなっているので、 移行時は明示的に属性を付ける必要がある。

CORS

  • 以下の指定で、CORS (Cross-Origin Resource Sharing) を有効化する。

    // CORS (Cross-Origin Resource Sharing)の有効化
// 別ドメイン上で動作する Web アプリからアクセス可能に設定。
config.EnableCors();

認証

Web API の認証は、OAuth 2.0 の Bearer Token を使用するのが一般的になりつつある。

// Web API configuration and services
// 「Bearer Token」認証のみを使用するように、Web API を設定。
config.SuppressDefaultHostAuthentication();
config.Filters.Add(new HostAuthenticationFilter(OAuthDefaults.AuthenticationType));

ApiControllerの例

基本

Web API を利用した場合のコントローラの例を以下に示す。

同じコントローラの中で、
GET に対応したメソッドを複数定義したい場合などは、
以下のようにオーバーロードで対応できる。

public class ValuesController : ApiController
{
    // GET api/values
    public IEnumerable<string> Get()
    {
        return new string[] { "value1", "value2" };
    }

    // GET api/values/5
    public string Get(int id)
    {
        return "value";
    }

    // POST api/values
    public void Post([FromBody]string value)
    {
    }

    // PUT api/values/5
    public void Put(int id, [FromBody]string value)
    {
    }

    // DELETE api/values/5
    public void Delete(int id)
    {
    }
}

バインディング

基本的に、モデル・バインディングを使用する。

モデル・バインディング

モデル・バインディングは、以下のように実装できる。

.\SPA_Sample\Models\WebApiParams を使用して ModelBinding している。

補足: ASP.NET Web API 2 のバインディングが 「カオス（と言うかファジー）」と言われるのは、 単純型はクエリ文字列、複雑型はボディという 暗黙の規約があるためである。 ASP.NET Core では [ApiController] 属性を付けると この推論規則が明文化され、 [FromBody] / [FromQuery] / [FromRoute] / [FromForm] を 明示することで曖昧さを排除できる。 Swagger (OpenAPI) の定義書生成の精度も上がる。

その他のバインディング

モデル・バインディングを使用しない方法。

CORS

CORS (Cross-Origin Resource Sharing) に対応する場合、

EnableCors属性

前述の、WebApiConfig での CORS の有効化を行った後に、
以下のように ApiController に EnableCors 属性を指定する。

/// <summary>OAuthResourceServerのApiController（ライブラリ）</summary>
[Authorize]
[EnableCors(
    // リソースへのアクセスを許可されている発生元
    origins: "*",
    // リソースによってサポートされているヘッダー
    headers: "*",
    // リソースによってサポートされているメソッド
    methods: "*",
    //
    SupportsCredentials = true)]
public class OAuthResourceApiController : ApiController
{

移行メモ（正誤）: 上記のコード例は origins: "*" と SupportsCredentials = true を併用しており、 そのままでは動作しない。 CORS (Cross-Origin Resource Sharing) の仕様上、 資格情報付きリクエスト（withCredentials）では Access-Control-Allow-Origin: * は許可されず、 具体的なオリジンを返す必要がある。 資格情報を伴う場合は origins に許可するオリジンを列挙すること。

認証CookieをCORSで送信

以下が参考になるが、

最近の OAuth 2.0 や OpenID Connect 等では、認証 Cookie は使用しないで、
Bearer Token というものを HTTP ヘッダに付与して認証・認可するのが
一般的になってきている。CORS の認証などもコレによって行う。

補足（最新化）: 元の記述では「Implicit Grant と呼ばれる WebAPI 専用フロー」に取り消し線が引かれていたが、 これは正しい判断であった。 Implicit Grant は OAuth 2.0 Security BCP で非推奨とされ、 OAuth 2.1 では廃止されている。 現在は SPA であっても Authorization Code + PKCE を使うのが正しい。

なお、Cookie を使わず Bearer Token にすることで CSRF（MS_CSRFCountermeasures.md）の主要な経路は塞がるが、 トークンを localStorage に置くと XSS で盗まれる。 どちらの脅威を取るかの判断が必要である。

その他

ActionFilterAttribute

前後処理の実装に、MVC のようにベースクラスが使用できなくなったため、
WebAPI 用の FilterAttribute（System.Web.Http.Filters.ActionFilterAttribute）を使用する。

  • なお、System.Web.Http を使用するには、Microsoft.AspNet.WebApi.Core を
    インストールする必要がある。

  • また、WebAPI 機能を使う際には、Microsoft.AspNet.WebApi.* のインストールが必要になる。

  • Open棟梁 の実装例（MyBaseAsyncApiController.cs）

補足: MVC 用（System.Web.Mvc）と Web API 用（System.Web.Http）に 同名の ActionFilterAttribute が別々に存在する点が ASP.NET Web API 2 のハマりドコロである。 using を取り違えるとフィルタが呼ばれない。 ASP.NET Core では統合され、この問題は無くなっている。

OWIN

ASP.NET Web API 2 から OWIN 対応され、セルフホストが可能になっている。

参考

Tags: .NET開発, 通信技術, OWIN, .NET Core, ASP.NET, ASP.NET Web API

このWikiは「Open棟梁Project」,「OSSコンソーシアム 開発基盤部会」によって運営されています。

NetDevInfraWiki

マイクロソフト系技術情報 Wiki
Open 棟梁 Wiki

（未着手）

開発基盤部会 Wiki

移行管理: DONE ／ TODO

Clone this wiki locally