C#のASP.NETでAPIレスポンスをJSONにする方法！Webアプリ開発初心者向けの完全解説ガイド
生徒
「C#を使ってWebアプリを作っているのですが、画面の裏側でデータをやり取りする仕組みについて勉強しています。インターネットで調べていると、APIとかJSONという言葉がよく出てくるのですが、これは一体何でしょうか？」
先生
「とても大切なところに目をつけましたね。APIはシステム同士が会話をするための窓口のようなもので、JSONはその会話で使われる共通の言葉、つまりデータの形式のことです。C#のASP.NETという仕組みを使うと、このJSONという形式のデータをとても簡単に作って返すことができます。」
生徒
「パソコンの操作もまだ不慣れで、プログラミングも始めたばかりなのですが、そんな私でも作れるようになりますか？」
先生
「大丈夫ですよ。今回は専門用語を身近な例えに置き換えながら、具体的なプログラムの書き方まで一つずつ丁寧に進めていきましょう。まずは基本的な仕組みから一緒に見ていきましょう！」
1. Webアプリ開発におけるAPIとJSONの基本概念
プログラミング未経験の方にとって、API（エーピーアイ）やJSON（ジェイソン）という言葉は難しく感じるかもしれません。まずはこの二つの役割を、私たちが日常で行っている飲食店の注文に例えて考えてみましょう。
Webアプリの世界では、スマホやパソコンの画面が「お客さん」、裏側で動いているプログラムが「厨房の料理人」です。お客さんがメニューを見て「ハンバーグをください」と注文を伝えてくれる「店員さん」の役割を果たすのがAPIです。正式にはアプリケーション・プログラミング・インターフェースと呼びますが、要するに「外部からの要求を受け付ける窓口」のことです。
そして、店員さんが厨房から出来上がった料理をお客さんのテーブルに運ぶとき、お皿に綺麗に盛り付けられた状態になっていますよね。この料理の盛り付け方に相当するのがJSONです。JSONはテキスト、つまり文字だけで書かれたデータの表現方法で、人間にとってもコンピュータにとっても非常に読みやすく、中身が理解しやすいという特徴を持っています。C#のWebアプリ開発フレームワークであるASP.NET（エーエスピーネット）を使用すると、このJSONデータを自動的に組み立てて、インターネットを通じて送り出す仕組みを簡単に構築することができます。
2. JSON形式のデータ構造と特徴を理解する
JSONがどのような見た目をしているのか、まずは文字の並び方を確認してみましょう。JSONは基本的に波括弧（{ }）で全体を囲み、その中に「名前」と「値」のペアをコロン（:）で区切って並べていきます。これをプログラミングの用語ではキーと値のペアと呼びます。
例えば、一人の生徒の情報をJSONで表現すると、名前が「太郎」、年齢が「十五」という情報を以下のように書き表すことができます。文字列を表すときはダブルクォーテーション（" "）で囲むという約束事があります。
{
"name": "太郎",
"age": 15
}
このように、非常にシンプルで無駄がない形式になっているため、インターネット上を流れるデータの量を小さく抑えることができます。結果として、スマートフォンの通信量を節約できたり、アプリの表示速度が速くなったりするという大きなメリットがあります。C#のプログラムで作成したデータを、このJSON形式に変換してあげることを、専門用語でシリアライズ（初期化や直列化）と呼びます。逆に、届いたJSONデータをC#のプログラムで扱える形に戻すことをデシリアライズと呼びます。この言葉は少し難しいですが、データを荷造りしたり荷解きしたりするイメージを持つと分かりやすいでしょう。
3. 開発環境の準備とASP.NETのコントローラー作成
C#でWebアプリを作るためには、マイクロソフトが提供しているASP.NET Core（エーエスピーネットコア）という仕組みを利用するのが一般的です。Webアプリの中で、外部からのリクエスト（注文）を受け取って処理を振り分ける中心的な存在をコントローラー（Controller）と呼びます。コントローラーは、料理店でいうところの「注文をさばくフロアマネージャー」のような存在です。
パソコンの操作に慣れていない方でも、開発ツールであるVisual Studioなどの指示に従ってWeb APIのプロジェクトを作成すると、自動的にこのコントローラーの土台となるファイルが作られます。プログラムを書くときは、まず「このクラスはコントローラーですよ」という目印をつける必要があります。クラスとは、プログラムの機能やデータを一まとめにした設計図のようなものです。C#では、クラスの名前の上に[ApiController]という特別な記述をすることで、システムに対してWeb用の窓口であることを教えてあげます。
4. 最もシンプルな文字列データをJSONとして返すプログラム
それでは、実際にC#のコードを書いて、最も単純なJSONデータを返却する仕組みを作ってみましょう。今回は、挨拶の言葉を返すだけのシンプルなAPIを作成します。以下のプログラムをご覧ください。
using Microsoft.AspNetCore.Mvc;
[ApiController]
[Route("api/[controller]")]
public class HelloController : ControllerBase
{
[HttpGet]
public IActionResult GetHello()
{
var response = new { message = "こんにちは、世界！" };
return Ok(response);
}
}
このプログラムの中に登場する用語の解説をします。[HttpGet]というのは、インターネットのブラウザなどで「このURLのページを表示して」と普通にお願いされたときに動く処理であることを示しています。IActionResult（アイアクションリザルト）は、処理の結果として画面やデータを返しますよという宣言です。そして、return Ok(response);と書くことで、通信が成功したという意味のステータスコード二百という番号と一緒に、データをJSONに変換して送り出してくれます。このプログラムを実行して、特定のURLにアクセスしたときの出力結果は以下のようになります。
{"message":"こんにちは、世界！"}
自動的に波括弧で囲まれたJSON形式に変換されていることが確認できますね。手動で難しい文字の組み立てをしなくても、ASP.NETが裏側で自動的に変換の作業を代行してくれているのです。
5. 複数の項目を持つデータオブジェクトをJSONに変換する方法
先ほどは一つの文字だけを返しましたが、実際のWebアプリ開発では、名前や日付、数値など、たくさんの種類のデータをまとめて一度に返したい場合がほとんどです。そのようなときは、C#の中でクラス（Class）と呼ばれるデータの設計図を定義して、それを活用します。
ここでは、ある商品の情報（商品ID、商品名、価格）を管理するための設計図を作り、その中に具体的なデータを入れてJSONとして出力させてみましょう。まずは商品の設計図となるクラスを以下のように用意します。
public class Product
{
public int Id { get; set; }
public string Name { get; set; }
public int Price { get; set; }
}
ここで登場するint（イント）は整数、つまり数字を入れるための箱を意味しており、string（ストリング）は文字列、つまり文字を入れるための箱を意味しています。これらを使って、コントローラーの中で具体的なデータを作成して返却するプログラムが以下となります。
using Microsoft.AspNetCore.Mvc;
[ApiController]
[Route("api/[controller]")]
public class ProductController : ControllerBase
{
[HttpGet]
public IActionResult GetProduct()
{
Product item = new Product();
item.Id = 101;
item.Name = "美味しいリンゴ";
item.Price = 250;
return Ok(item);
}
}
プログラムの中でnew Product()と書くことで、設計図から本物のデータのかたまりを作り出しています。これをインスタンス化と呼びます。このプログラムを実行した際の出力結果は以下の通りです。
{"id":101,"name":"美味しいリンゴ","price":250}
複数のデータ項目がカンマ（,）で区切られて、綺麗なJSON形式になっていることがわかります。C#のアルファベットの大文字で始めた名前が、JSONになるときには自動的に小文字で始まる標準的な表記に変換されるのも、ASP.NETの親切な機能の一つです。
6. データの配列やリストをJSONの並びとして出力する手法
一つの商品だけでなく、お店にある商品の一覧のように、たくさんのデータをまとめて同時に返したい状況もよくあります。プログラミングの世界では、同じ種類のデータを一列に並べて管理する仕組みをリスト（List）や配列と呼びます。学校の出席簿や、お買い物のチェックリストのようなものをイメージしてください。
C#ではList<型名>という書き方を使うことで、特定のデータを何個でも詰め込むことができる便利なカゴを用意することができます。今回は、先ほど作った商品の設計図を使って、二つの商品が含まれたリストを作成し、それを一気にJSONとして返却してみましょう。
using System.Collections.Generic;
using Microsoft.AspNetCore.Mvc;
[ApiController]
[Route("api/[controller]")]
public class ProductListController : ControllerBase
{
[HttpGet]
public IActionResult GetProductList()
{
List<Product> products = new List<Product>();
Product item1 = new Product { Id = 1, Name = "ノートパソコン", Price = 85000 };
Product item2 = new Product { Id = 2, Name = "無線マウス", Price = 35000 };
products.Add(item1);
products.Add(item2);
return Ok(products);
}
}
プログラムの中にあるproducts.Add(item1);という部分は、用意したカゴの中に商品データを追加していく操作を意味しています。これをそのまま返却すると、出力結果は以下のようになります。
[{"id":1,"name":"ノートパソコン","price":85000},{"id":2,"name":"無線マウス","price":35000}]
全体が四角い大括弧（[ ]）で囲まれているのが確認できますね。JSONのルールでは、大括弧はデータの集まり（配列やリスト）を表すことになっています。大括弧の中に、先ほど学習した波括弧のデータがカンマで区切られて並んでいるため、これが複数のデータの一覧であることがシステム側にも一目で伝わります。
7. エラー発生時に状況を伝えるJSONレスポンスを返す工夫
Webアプリを運用していると、常に正しいデータだけが返せるわけではありません。例えば、探している商品の番号が見つからなかったときや、入力されたデータに間違いがあったときなど、エラーが発生することもあります。そのような場合でも、ただ動かなくなるのではなく、「何が原因で失敗したのか」をJSONの形式で親切に教えてあげる必要があります。
ASP.NETでは、通信が失敗したことを表すためにBadRequest（バッドリクエスト）やNotFound（ノットファウンド）といった命令が用意されています。これらの中にエラーメッセージを詰め込んで返すことで、安全で親切なAPIを作ることができます。具体的な実装例を見てみましょう。
using Microsoft.AspNetCore.Mvc;
[ApiController]
[Route("api/[controller]")]
public class ErrorController : ControllerBase
{
[HttpGet("{id}")]
public IActionResult CheckId(int id)
{
if (id < 0)
{
var errorResponse = new { error = "無効な番号です", detail = "ゼロ以上の数値を指定してください。" };
return BadRequest(errorResponse);
}
var successResponse = new { status = "成功", message = "正しい番号が受け付けられました。" };
return Ok(successResponse);
}
}
このプログラムでは、もしURLから送られてきた番号がゼロより小さいマイナスの数値だった場合に、if文の条件が満たされ、エラー用のJSONデータが作成されます。そしてBadRequestを通じて、正しくない要求であったという通知とともにデータが返されます。マイナスの数値を指定してアクセスしたときの出力結果は以下のようになります。
{"error":"無効な番号です","detail":"ゼロ以上の数値を指定してください。"}
このようにエラーの理由を文字で返してあげることで、アプリを利用している開発者や画面側のプログラムが、次にどうやって修正すれば良いのかを正確に判断できるようになります。これはプロの開発現場でも非常に重要視される設計手法です。
