ASP.NET の Web API と MVC コントローラの違い（JSON を返す社内 API はどっち）

みなさんこんにちは！ヒロポンです！

社内システムから JSON を返すちょっとした API を作りたい。よくある話ですよね。別の画面から叩いたり、Excel マクロから叩いたり、隣のチームのバッチから叩いたり。

で、いざ手を動かそうとして固まる。「これ、いつもの MVC のコントローラでいいの？？ それとも Web API ってやつ？」

ASP.NET の Web API と MVC の違い。名前が似てるうえに、MVC のコントローラでも JSON は返せる。だから最初はほんとに見分けがつかない。俺も昔、全部 MVC のコントローラで JSON を返してました。で、途中で「あれ、これ Web API のほうが楽だったのでは」って気づいたクチです。

今回はこの2つの役割の違いと、「JSON を返す社内 API はどっちで作るのが素直か」を、コピペで動く形で並べていきます。同じプロジェクトに両方混ぜてルーティングで詰まる、っていう最初のハマりどころも先に潰しておく。

忙しい人向けに最初にまとめ

• MVC コントローラは基本 View（HTML 画面）を返す係。return Json(...) で JSON も返せるが、それは明示指定が要る
• Web API（ApiController）は基本 データ（JSON / XML）を返す係。戻り値にデータを返すだけで、Accept ヘッダに応じてフレームワークが JSON か XML に変換する（コンテンツネゴシエーション）
• JSON を返す社内 API を作るなら Web API が素直。REST の作法（Get / Post、404 を返す等）が最初から乗っているから
• 最初のハマり: 同一プロジェクトに両方置くと、api/ プレフィックスで先に分けておかないと、リクエストが MVC 側に吸われる
• ASP.NET Core では両者は統合済み。[ApiController] 属性で API として振る舞わせる

コードは中盤に全部あります。まずは「そもそも何が違うのか」から。

そもそも Web API と MVC コントローラは何が違うのか

一言でいうと、返すものが違う。出発点はここです。

MVC のコントローラは、画面（HTML）を返すために生まれたもの。System.Web.Mvc.Controller を継承して、アクションが View() を返し、Razor が .cshtml を HTML に組み立てる。人間がブラウザで見る画面の担当です。

Web API（ApiController）は、データを返すために生まれたもの。System.Web.Http.ApiController を継承して、アクションがオブジェクトをそのまま返すと、フレームワークがそれを JSON（や XML）にシリアライズする。人間じゃなくて、別のプログラムが叩く前提の担当です。

Web API は、ASP.NET でデータ（JSON / XML）を HTTP 経由で返すことに特化した、REST 作法をあらかじめ備えたフレームワークです。

.NET Framework の世界では、この2つは別々のフレームワークでした。名前空間も基底クラスもルーティングの仕組みも別。ここを「なんとなく似たもの」と思ってると、後でルーティングに足をすくわれます。

対応マップ — MVC コントローラと Web API を6観点で比較

まず全体像を一枚で、こんな感じにまとめました。どこがどう違うのか、観点ごとに並べます。

太字の「本命用途」の行が結論です。人が見る画面なら MVC、他のプログラムが叩く JSON なら Web API。ここさえ押さえておけば、細かい違いは後から効いてきます。

違い1: 返すもの — MVC は View、Web API はデータ

コードで見ると一発です。まずは MVC のコントローラ。

// ASP.NET MVC 5 (System.Web.Mvc)
public class ProductsController : Controller
{
    // 既定は View (HTML) を返す
    public ActionResult Index()
    {
        var products = _repo.GetAll();
        return View(products);   // Views/Products/Index.cshtml を描画
    }

    // JSON を返したいなら明示的に Json() を使う
    public ActionResult ListJson()
    {
        var products = _repo.GetAll();
        return Json(products, JsonRequestBehavior.AllowGet);
    }
}

Index() は View を返す。JSON がほしい時は ListJson() みたいに毎回 Json(...) を明示する。「なんで GET だと怒られるの？？」でおなじみの、JsonRequestBehavior.AllowGet の付け忘れも MVC あるあるです。

対して Web API はこう。

// ASP.NET Web API 2 (System.Web.Http)
public class ProductsController : ApiController
{
    // 戻り値はデータそのもの。JSON/XML はフレームワークが決める
    public IEnumerable<Product> Get()
    {
        return _repo.GetAll();   // Accept に応じて JSON か XML にシリアライズ
    }

    public IHttpActionResult Get(int id)
    {
        var p = _repo.Find(id);
        if (p == null) return NotFound();   // 404 を素直に返せる
        return Ok(p);
    }
}

Get() は Product のリストをそのまま返してるだけ。Json() は書いてない。なのにクライアントには JSON が返る！！ ここが Web API の気持ちよさで、「データを返す」ことに集中できる。NotFound() で 404、Ok() で 200 みたいに、HTTP のステータスを素直に扱える口も最初から付いてます。

いい感じに役割で分かれてるのが分かりますよね。MVC は「画面を組む」、Web API は「データを渡す」。

違い2: ルーティングの既定が違う

返すものと並んで大事なのがルーティング。混在時のハマりの震源地はここです。

• MVC: {controller}/{action}/{id}。つまり /Products/Index のようにアクション名が URL に出る
• Web API: api/{controller}/{id}。アクション名は URL に出ず、HTTP メソッド（GET / POST）でアクションを選ぶ

図にするとこう。同じ「products」でも、api/ が付くかどうかで行き先が変わります。

設定はそれぞれ別ファイルに書きます。App_Start の下に、MVC 用と Web API 用で分かれている。

// App_Start/WebApiConfig.cs — Web API は api/ プレフィックスで分ける
public static void Register(HttpConfiguration config)
{
    config.MapHttpRoute(
        name: "DefaultApi",
        routeTemplate: "api/{controller}/{id}",
        defaults: new { id = RouteParameter.Optional }
    );
}

// App_Start/RouteConfig.cs — MVC は従来どおりアクション名込み
routes.MapRoute(
    name: "Default",
    url: "{controller}/{action}/{id}",
    defaults: new { controller = "Home", action = "Index", id = UrlParameter.Optional }
);

肝は、Web API を api/ で先に分けておくこと。これをやっておかないと、次のハマりに直行します。

違い3: モデルバインディングとコンテンツネゴシエーション

もう1つ、地味だけど詰まる違い。入力（リクエストの受け取り方）と出力（レスポンスの形式決め）の既定が違います。

• 出力: MVC は「自分で Json() を指定する」。Web API は「Accept ヘッダを見てフレームワークが JSON か XML を選ぶ」（コンテンツネゴシエーション）
• 入力: Web API は、複雑な型（クラス）を1つだけ、リクエストボディから受け取るのが既定。複数のクラスをボディから受け取ろうとすると、片方が null になって「なんで値が入ってないの？？」と詰まる

この入力の既定は、最初かなり驚きます。

public class ProductsController : ApiController
{
    // ✅ ボディの複雑な型は1つだけ。これは素直に入る
    public IHttpActionResult Post(Product product)
    {
        _repo.Add(product);
        return Created($"api/products/{product.Id}", product);
    }

    // ⚠️ 複雑な型を2つボディから取ろうとすると、片方が null になりがち
    // public IHttpActionResult Post(Product product, Category category) { ... }
}

MVC のノリで「引数にクラスを2つ並べれば両方フォームから拾ってくれる」と思ってると、Web API では素通りされる。ここは MVC と Web API でモデルバインディングの既定がそもそも違う、と割り切っておくのが早いです。

ハマりポイント: 同じプロジェクトに両方混ぜるとルーティングで詰まる

業務SEが最初にほぼ確実に踏むやつ、行きます。実体験ベースで書きます。

既存の MVC アプリに「あとから JSON API を足したい」ってなって、Web API のコントローラを1個追加する。よくある流れです。で、/api/products を叩く。すると……404 でビューが見つからないと言われる。あるいは MVC 側の別のアクションに吸い込まれる。

犯人はルート登録の順番と api/ プレフィックス。MVC の {controller}/{action}/{id} は貪欲なので、api を controller 名、products を action 名だと解釈して MVC 側に持っていってしまう。

避け方は2つ。

1. Web API のルートを api/ プレフィックスで先に登録する（Global.asax で GlobalConfiguration.Configure(WebApiConfig.Register) を MVC の RouteConfig より先に呼ぶ）
2. 同名の Controller と ApiController を同じプロジェクトに置くなら、名前かフォルダで territory を明確に分ける

俺は昔これで、ProductsController（MVC）と ProductsController（Web API）を同名で置いてやらかしました。「Multiple types were found that match the controller named 'Products'」みたいな例外です。原因に気づくまで、ルーティングの登録順を行ったり来たり。小一時間、まるっと溶けました。名前を ProductsApiController に変えて、api/ プレフィックスを徹底したら、あっさり直る。

教訓は、MVC と Web API は同居できるが、URL の territory を先に分けておく。後から混ぜると、たいていここで足を取られます。

じゃあ、JSON を返す社内 API はどっちで作る？

判断軸をはっきりさせます。

他のプログラムが叩く JSON API を作るなら、Web API 一択でいい。理由はシンプル。Web API には「データを返す」「HTTP ステータスを素直に扱う」「Accept で形式を出し分ける」という REST の作法が最初から乗っている。MVC でも Json() を毎回書けば JSON は返せるけど、それは Web API が既定でやってくれることを手作業でなぞってるだけなんですよね。

逆に、人が見る画面（HTML）を返すなら MVC。そこは Web API の出る幕じゃない。

社内システムだと「画面もあるし、隣のチーム向けの API もほしい」という混在がよくあります。その時は、画面は MVC、API は Web APIで役割分担して、URL を api/ で分ける。これが .NET Framework 時代の素直な形です。

ASP.NET Core では、この2つは統合された

ここまで .NET Framework（System.Web 世代）の話をしてきました。あなたの現場が MVC 5 / Web API 2 なら、上の構図がそのまま効きます。

ただ、ASP.NET Core ではこの「2つの別フレームワーク」という構図は解消されています。Core では Controller も ApiController も区別がなくなり、どちらも ControllerBase（画面もやるなら Controller）を継承する。API として振る舞わせたいクラスには [ApiController] 属性を付けるだけ。ルーティングも [Route] 属性で統一されました。

いちばんシンプルな形だと、Core の最小 API はこれだけで JSON を返す社内 API になります。

// ASP.NET Core (最小 API): これだけで JSON を返す API になる
var app = WebApplication.Create();

app.MapGet("/api/products", () => new[]
{
    new { id = 1, name = "ねじ", price = 120 },
    new { id = 2, name = "ボルト", price = 240 },
});

app.Run();