1. JSONとは？APIとは？初心者にもわかりやすく解説

JSON（ジェイソン）とは、JavaScript Object Notationの略で、データを「名前」と「値」のペアで表すフォーマットのことです。例えば「名前がたろう、年齢が20歳」という情報は、次のように書きます。


{
  "name": "たろう",
  "age": 20
}

このJSONをインターネットで送受信する仕組みがAPI（エーピーアイ）です。アプリや他のサービスが、Railsのシステムにアクセスしてデータをもらったり、保存したりするための入口になります。

2. RailsのコントローラでJSONを返す方法

通常、RailsのコントローラはHTMLの画面を表示しますが、API用には画面ではなくJSONを直接返すように作ります。コントローラでJSONを返すには、render json:を使います。


class UsersController < ApplicationController
  def show
    user = User.find(params[:id])
    render json: user
  end
end

このコードは、指定されたユーザーの情報をJSON形式で返します。

3. ステータスコードとは？APIではとても大事！

ステータスコードは、APIの返事が成功だったか失敗だったかを相手に伝える3桁の番号です。以下が代表的なコードです：

200 OK：成功しました
201 Created：新しいデータを作成しました
400 Bad Request：リクエストが正しくありません
404 Not Found：データが見つかりません
500 Internal Server Error：サーバー側のエラーです

Railsではstatus:オプションでこのコードを指定できます。


render json: { error: "見つかりませんでした" }, status: :not_found

4. JSONの形はどうあるべき？シリアライズとは？

シリアライズとは、データをJSONの形に整えることです。Railsでは、自動でモデルの内容をJSONに変換してくれますが、そのままだと必要ない情報も含まれることがあります。

そこで、onlyやexceptを使って、必要な項目だけを指定できます。


render json: user.to_json(only: [:id, :name, :email])

このようにすることで、余計な情報を隠して、安全にデータをやりとりできます。

5. エラーを返すときのJSONの形式はどうする？

エラーが発生したときも、統一された形式でJSONを返すことが大切です。よく使われる形は以下のような構造です：


{
  "errors": [
    { "field": "email", "message": "メールアドレスは必須です" },
    { "field": "password", "message": "パスワードが短すぎます" }
  ]
}

このようにすれば、アプリ側でも表示しやすくなりますし、どこに何の問題があるかが一目でわかります。

6. バリデーションエラー時のレスポンス例

Railsでは、モデルにバリデーション（入力チェック）を設定できます。たとえば、ユーザー登録の際に必要な情報が足りないと、user.errorsにエラーが入ります。それをJSONで返すには次のようにします。


user = User.new(params.require(:user).permit(:name, :email))

if user.save
  render json: user, status: :created
else
  render json: {
    errors: user.errors.map { |field, msg| { field: field, message: msg } }
  }, status: :unprocessable_entity
end