【入門編】 API入力バリデーション：JSONスキーマによる構造検証 – Web APIアーキテクチャ・データ連携実践ガイド

はい、承知いたしました！REST APIの入力バリデーション、特にJSON Schemaを使った構造検証について、インフラやネットワークの初学者の方にも分かりやすく、現実世界の例えを交えながら、親しみやすいブログ記事に仕上げていきます。パケット構造やビット数といった専門用語は極力避け、APIがどのようにリクエストを受け取り、それをどうやって「検品」しているのかを、郵便配達のイメージで紐解いていきましょう。

—

APIからの「お手紙」、ちゃんと届いていますか？ JSON Schemaで間違いのないリクエストを送るコツ

皆さん、こんにちは！Web APIの世界を一緒に探求していくこのブログへようこそ。今回は、APIと上手に付き合うためにとっても大切な「API入力バリデーション」、中でも「JSON Schema」を使った構造検証について、基本の「キ」からじっくり学んでいきましょう。

「APIって何？」「バリデーションって聞くだけで難しそう…」と感じている方も大丈夫！今回は、日頃皆さんが目にしているであろう、身近な例え話をたくさん交えながら、APIがリクエストをどうやって受け取って、その内容をどうやってチェックしているのか、その裏側を優しく紐解いていきます。

1. APIは「郵便屋さん」！？リクエストって、実際どういうこと？

まず、APIが何をしているのか、イメージを掴むことから始めましょう。APIは、例えるなら「郵便配達員さん」のようなものです。

  • あなたのアプリ/システム: 手紙を書きたい「あなた」
  • API: 手紙を宛先に届けてくれる「郵便配達員さん」
  • リクエスト: あなたが郵便配達員さんに託す「手紙」
  • レスポンス: 郵便配達員さんがあなたに届けてくれる「返事」や「荷物」

さて、あなたが郵便配達員さんに手紙を託すとき、どんなことに気をつけますか？

  • 宛先（住所）は間違っていないか？
  • 手紙の内容（メッセージ）はちゃんと書かれているか？
  • 封筒はちゃんと閉じられているか？

APIへのリクエストも、これと似ています。あなたが書いた「手紙」、つまりAPIに送るデータ（リクエストボディ）が、APIという「郵便配達員さん」が正しく受け取ってくれるための「ルール」に沿っている必要があるんです。

2. なんで「ルール」が必要なの？ APIが困らないように！

もし、あなたが郵便配達員さんにおかしな手紙を渡したらどうなるでしょう？

  • 住所が書いていない手紙 → どこに届けたらいいか分からず、配達できません。
  • 中身がぐちゃぐちゃで読めない手紙 → どんなメッセージなのか理解できません。
  • 封筒が開いていて中身が飛び出しそうな手紙 → 途中で紛失したり、情報が漏れたりするかもしれません。

APIも同じです。もし、APIが期待していない形式のデータ（リクエストボディ）を受け取ってしまうと、

  • 「このデータ、どう扱っていいか分からないよ！」とエラーになってしまう。
  • 間違ったデータを受け取って、システムが予期せぬ動作をしてしまう。
  • セキュリティ上の問題を引き起こしてしまう。

…といった、困った事態が発生しかねません。

そこで登場するのが、今回ご紹介する「API入力バリデーション」という仕組みです。これは、APIがデータを受け取る前に、そのデータが「ちゃんとルールに沿っているか？」をチェックしてくれる「検品作業」のようなものなんです。

3. JSON Schemaって、いったい何者？ データのための「設計図」

APIとのやり取りでよく使われるデータの形式に「JSON」があります。JSONは、人間にもコンピューターにも分かりやすい、シンプルで構造化されたデータ形式なんですね。

例えば、ユーザー情報を送るときのJSONデータは、こんな風になっているかもしれません。

{
  "userName": "山田太郎",
  "age": 30,
  "email": "taro.yamada@example.com"
}

このJSONデータが、APIに正しく届くようにするためには、どんな情報が、どんな形式で、どんなルールで送られてくるべきか、あらかじめ決めておく必要があります。その「決まりごと」を、まるで「設計図」のように記述できるのが、JSON Schema なんです。

JSON Schemaは、JSON形式で書かれた「JSONデータの仕様書」のようなものです。これがあると、API側は「このJSONデータは、こういうルールでできているはずだ！」ということを理解できます。

4. JSON Schemaでできる！「構造検証」の具体的なチェック項目

JSON Schemaを使うと、APIに送られてくるJSONデータに対して、様々なチェックを行うことができます。今回は、特に「構造検証」という観点から、いくつか代表的なチェック項目を見ていきましょう。

4.1. 「この項目は絶対必要！」必須項目のチェック

手紙の宛名のように、APIに送るデータにも「これは絶対に必要！」という項目がありますよね。JSON Schemaでは、どの項目が必須かを指定できます。

例えば、先ほどのユーザー情報で、userName と age は必須だけど、email は任意（なくてもOK）としたい場合、JSON Schemaではこのように記述します。

{
  "type": "object", // 全体はオブジェクト（{}で囲まれた部分）です
  "properties": { // オブジェクトの中身（プロパティ）の定義です
    "userName": {
      "type": "string", // userNameは文字列（テキスト）であること
      "description": "ユーザーの名前" // これは説明なので、必須ではありません
    },
    "age": {
      "type": "integer", // ageは整数（数字）であること
      "description": "ユーザーの年齢"
    },
    "email": {
      "type": "string", // emailも文字列であること
      "description": "ユーザーのメールアドレス（任意）"
    }
  },
  "required": [ // ここが重要！必須項目を指定します
    "userName",
    "age"
  ]
}
  • "required": ["userName", "age"] と指定することで、「userName と age は、たとえ値が空っぽでも、必ずJSONの中に存在していなければならない」というルールが定義されます。
  • もし、userName や age がリクエストに含まれていないと、APIは「あ、この手紙、宛名が抜けてるよ！」と判断して、エラーを返してくれるわけです。

4.2. 「文字列は〇文字まで！」文字列の長さチェック

本文が長すぎると、郵便屋さんも大変ですよね。APIに送る文字列データも、長すぎたり短すぎたりすると、システムがうまく処理できなかったり、セキュリティ上の問題につながったりすることがあります。JSON Schemaでは、文字列の長さを細かく指定できます。

例えば、userName は1文字以上20文字以下にしたい、というルールを追加してみましょう。

{
  "type": "object",
  "properties": {
    "userName": {
      "type": "string",
      "description": "ユーザーの名前",
      "minLength": 1, // 文字数は1文字以上であること
      "maxLength": 20 // 文字数は20文字以下であること
    },
    "age": {
      "type": "integer",
      "description": "ユーザーの年齢"
    },
    "email": {
      "type": "string",
      "description": "ユーザーのメールアドレス（任意）"
    }
  },
  "required": [
    "userName",
    "age"
  ]
}
  • "minLength": 1 は「最低でも1文字は必要だよ」
  • "maxLength": 20 は「20文字を超えちゃダメだよ」

という、分かりやすいルールですね。

4.3. 「この形式じゃないとダメ！」正規表現パターンチェック

メールアドレスや電話番号など、特定の形式が決まっているデータもありますよね。JSON Schemaでは、「正規表現」という強力なパターンマッチング機能を使って、データの形式を厳密にチェックすることができます。

例えば、email の形式が、一般的なメールアドレスの形式（@ が含まれていて、ドメイン部分があるなど）になっているかチェックしたい場合、このように記述します。

{
  "type": "object",
  "properties": {
    "userName": {
      "type": "string",
      "description": "ユーザーの名前",
      "minLength": 1,
      "maxLength": 20
    },
    "age": {
      "type": "integer",
      "description": "ユーザーの年齢"
    },
    "email": {
      "type": "string",
      "description": "ユーザーのメールアドレス",
      "format": "email" // JSON Schemaには、emailのフォーマットチェックが標準で用意されています！
      // もしくは、より厳密に正規表現で指定することも可能です。
      // "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
    }
  },
  "required": [
    "userName",
    "age"
  ]
}
  • "format": "email" と書くだけで、多くのJSON Schemaバリデーターが、標準で定義されているメールアドレスの形式チェックを行ってくれます。これはとても便利ですね！
  • もし、さらに特殊な形式のチェックが必要な場合は、"pattern" に正規表現を直接記述することもできます。正規表現は少し難しく聞こえるかもしれませんが、"@" が入っているか、ドット(.)の後にアルファベットが2文字以上続いているか、といった規則を記述するための「魔法の言葉」のようなものです。

5. 実際に使ってみよう！バリデーションの仕組み

では、これらのJSON Schemaのルールは、実際にどうやってAPIで使われるのでしょうか？

APIを開発している側は、まず「このAPIには、こういうJSON Schemaのルールでデータが送られてくるはずだ」というJSON Schemaを定義しておきます。

そして、APIにリクエストが送られてきたら、そのリクエストボディのJSONデータを、あらかじめ定義しておいたJSON Schemaと照らし合わせて「検証」する、という流れになります。

5.1. バリデーションが成功した場合

リクエストボディのJSONデータが、JSON Schemaの全てのルール（必須項目があるか、型は合っているか、長さはOKか、形式は合っているか…など）を満たしている場合、APIはそのリクエストを「正しい手紙」として受け取り、処理を進めます。

5.2. バリデーションが失敗した場合

もし、リクエストボディのJSONデータが、JSON Schemaのどれか一つのルールでも満たしていなかった場合、APIは「この手紙、どこかおかしいよ！」と判断し、クライアント（リクエストを送ってきた側）にエラーメッセージを返します。

例えば、必須項目であるageが抜けていたら、以下のようなエラーレスポンスが返ってくるかもしれません。

{
  "error": "Validation failed",
  "details": {
    "age": "is a required property"
  }
}

このように、API側で早期に不正な入力を「検品」し、エラーを返すことで、後工程での無駄な処理を防ぎ、システム全体の安定性を高めることができるんです。

6. まとめ：APIとの信頼関係を築くために

今回は、API入力バリデーションの基本である「JSON Schemaによる構造検証」について、郵便配達の例え話を交えながら解説しました。

  • APIは郵便配達員さん、リクエストは手紙。
  • JSON Schemaは、その手紙（JSONデータ）の「設計図」や「ルールブック」。
  • 必須項目、文字列の長さ、正規表現パターンなど、様々なチェックができる。
  • バリデーションによって、APIは不正な入力を早期に発見し、エラーを返すことができる。

APIとのやり取りは、まさに「信頼関係」です。APIに「このデータは信用できますよ」と伝えるために、そしてAPIから「あなたのリクエストはちゃんと受け付けましたよ」という確かな返事をもらうために、JSON Schemaのようなバリデーションの仕組みは、開発者にとっても、APIを利用する側にとっても、なくてはならないものなんです。

「なんだか難しそう…」と感じていた皆さんも、今日でJSON Schemaのイメージが少しでも掴めたのではないでしょうか？
次回は、さらに「API入力バリデーション」の奥深い世界を探求していきましょう！

—

スポンサーリンク

コメント

タイトルとURLをコピーしました