😎

WebAPI

に公開
API
基礎知識
idea

アプリ開発のための Web API 入門（HTTP / URL / JSON / SQL / OpenAPI を体系的に理解する）

モバイルアプリ（iOS / Android / Flutter）を作っていると、必ず出てくる単語があります。

  • GET / POST / PATCH / DELETE
  • JSON
  • HTTP
  • URL（パス）
  • 認証（Bearer トークン）
  • SQL
  • OpenAPI（Swagger）

このあたりが「全部バラバラに見える」と、API仕様書（OpenAPI）を読んでも実装につながりません。

この記事は、初学者向けに アプリ開発に必要な Web API の知識を体系的にまとめたものです。
ゴールは「OpenAPI を見て、どのURLに何を送って何が返るか」を自力で理解できる状態です。

この記事のゴール

読み終わったあとに、次の質問に答えられるようになります。

  • 「URL（パス）」って何？アプリのどこで使う？
  • GET と POST の違いは？
  • JSON は何のための形式？
  • HTTP と SQL の役割の違いは？
  • 401 と 403 の違いは？
  • OpenAPI（Swagger）は何を決めている？

全体像：アプリとサーバーのデータの流れ

まず、アプリ開発で最重要の一枚絵です。

アプリ（フロント）
→ HTTPでサーバーにリクエスト（お願い）
→ サーバーがDBを操作（SQLやORM）
→ HTTPでレスポンス（返事）
→ アプリがJSONを読んで画面に反映

この流れの中で登場する用語の役割はこうです。

  • HTTP：アプリとサーバーが会話するルール
  • URL（パス）：サーバーの「窓口の住所」
  • メソッド（GET/POST...）：その窓口で何をしたいか
  • JSON：やりとりするデータの書き方
  • SQL：サーバーがDBに命令する言語（アプリは普通触らない）
  • OpenAPI：上の全部を仕様書としてまとめたもの

クライアントとサーバー

クライアント（Client）

ユーザーが操作する側。つまりスマホアプリやWebブラウザ。

  • 画面表示
  • 入力受付
  • ボタン押下
  • APIを呼ぶ（通信する）

サーバー（Server）

データを保存・共有し、権限チェックや整合性を守る側。

  • ユーザー情報
  • 投稿
  • コメント
  • いいね
  • サークル情報
  • 通報

などをDBに持ちます。

HTTPとは：アプリとサーバーが話すための共通ルール

HTTPは一言でいうと、アプリとサーバーの会話の形式です。

  • アプリが送る：リクエスト（request）
  • サーバーが返す：レスポンス（response）

この「お願い→返事」の形式が決まっているから、iOSでもAndroidでも、バックエンドがNodeでもPythonでも通信できます。

URL（パス）とは：サーバーの窓口の住所

URL（正確にはパス）は、サーバーにある窓口の住所です。

例：

  • /api/v1/me：自分の情報を扱う窓口
  • /api/v1/circles：サークル関連の窓口
  • /api/v1/posts：投稿関連の窓口

重要なポイント：

  • URLはアプリ画面に表示するためのものではない（普通はユーザーに見せない）
  • アプリが内部でサーバーに通信するための宛先

ベースパス（prefix）の考え方

OpenAPIでこう書かれていることがあります。

servers:
  - url: /api/v1

これは「すべての窓口は /api/v1 から始まる」という意味です。

なので、OpenAPIで /me と書いてあったら実際の宛先は

  • /api/v1/me

になります。

HTTPメソッドとは：窓口で何をしたいかを示す

同じURLでも「やりたいこと」が違うことがあります。
それを区別するのがHTTPメソッドです。

最初はこの4つでOKです。

  • GET：取得（読む）
  • POST：作成（増やす）
  • PATCH：更新（部分的に直す）
  • DELETE：削除（消す）

例：同じ /circles でも操作が違う

  • GET /api/v1/circles
    → サークル一覧を取得したい

  • POST /api/v1/circles
    → 新しいサークルを作りたい

URLは同じでも、メソッドが違うと意味が変わります。

リクエストの送り方：2種類ある

リクエスト（お願い）でよく使うのは2つです。

1) クエリパラメータ（URLの後ろ）

検索条件や絞り込み条件を渡すときに使います。

例：

GET /api/v1/circles?sort=latest&tag=sports&page=1

  • sort：並び順（latest / popular など）
  • tag：タグで絞る
  • page：ページ番号

2) requestBody（JSON本文）

作成・更新などで「中身」を送るときに使います。

例（作成）：

POST /api/v1/circles

送るJSON：

{
  "name": "テニスサークル",
  "description": "週2で活動",
  "is_public": true,
  "tags": ["sports"]
}

GETは基本的に requestBody を使わず、条件はクエリで渡すことが多いです。

JSONとは：データをやりとりするための書き方

JSONは「データを文字で表すための形式」です。
APIではほぼ標準的にJSONが使われます。

JSON（オブジェクト）

{
  "display_name": "miki",
  "grade": 3,
  "is_public": true
}

JSON（配列）

{
  "tags": ["sports", "music"]
}

JSONが使われる場面：

  • アプリ → サーバー：送るデータ（requestBody）
  • サーバー → アプリ：返すデータ（response body）

レスポンスとステータスコード：成功/失敗の種類

サーバーはレスポンスで

  • ステータスコード（数字）
  • JSON（データやエラー）

を返します。

最低限覚えるステータスコード

  • 200：成功（取得・更新など）
  • 201：成功（作成）
  • 400：入力が間違っている（バリデーションエラー）
  • 401：認証できない（ログインしてない / トークン無効）
  • 403：権限がない（ログインはしてるが操作できない）
  • 404：見つからない
  • 500：サーバー側エラー

401 と 403 の区別だけは超重要です。

  • 401：誰かわからない（身分証がない/無効）
  • 403：誰かはわかるが許可がない（権限不足）

認証（Bearerトークン）とは：ログインしている人の証明

認証は「この操作をしているのは誰か」を証明する仕組みです。

ログイン後、アプリはトークン（身分証）を持ちます。
APIを呼ぶときにヘッダーに付けて送ります。

例：

Authorization: Bearer <token>

サーバーはこのトークンを検証して

  • OK：ユーザーを特定して処理を進める
  • NG：401を返す

OpenAPIで bearerAuth が指定されている場合は

  • 基本的にこのトークンが必要

という意味になります。

HTTP（GET / POST）と SQL の違い

ここは初学者が一番混乱しやすいポイントです。

結論：会話相手が違う。

  • HTTP：アプリ ↔ サーバー の会話
  • SQL：サーバー ↔ DB の会話

流れで理解する

  1. アプリ：GET /api/v1/posts（投稿ちょうだい）
  2. サーバー：DBへ問い合わせ（SQLやORMで取得）
  3. サーバー：結果をJSONにして返す
  4. アプリ：JSONを表示する

重要：アプリがSQLを直接叩くのは普通しません。
セキュリティと権限管理、設計のために「API経由」が基本です。

OpenAPI（Swagger）とは：APIの仕様書

OpenAPIは「APIのルールを文章としてまとめた仕様書」です。
YAMLやJSONで書かれ、チーム開発での認識ズレを減らします。

OpenAPIが決めること：

  • どんなパス（URL）があるか（paths）
  • 各パスで使えるメソッド（get/post/patch/delete）
  • 送るJSONの形（requestBody）
  • 返るJSONの形（responses）
  • パラメータ（query/path）
  • 認証方式（securitySchemes、security）
  • 共有できる型定義（components/schemas）

components/schemas の役割

JSONの「型（テンプレ）」です。

  • User
  • Profile
  • Circle
  • Post

などを定義して再利用できます。

required の役割

「必ず含めるべき項目」の指定です。
たとえば Profile なら display_name は必須、など。

実務で使えるチェックリスト（最低限）

フロント（アプリ側）がAPIを使うとき

  • 叩くパスは何か（/api/v1/...）
  • メソッドは何か（GET/POST/PATCH/DELETE）
  • クエリは何か（page, sort, tagなど）
  • bodyは必要か（POST/PATCHならJSON）
  • 認証が必要か（Authorizationヘッダー）
  • 成功時のJSONをどう画面に反映するか
  • 失敗時（401/403/400など）にどう表示するか

バック（サーバー側）がAPIを作るとき

  • OpenAPI通りの入力（DTO）を受け取る
  • OpenAPI通りのレスポンス形を返す
  • 認証でユーザー特定（Guard）
  • 権限チェック（owner/adminなど）
  • DB操作（SQL/ORM/Prisma）
  • エラー時に適切なステータスコードを返す

まとめ：最小暗記セット

  • URL（パス）：サーバーの窓口の住所
  • HTTP：アプリとサーバーが会話するルール
  • メソッド：何をしたいか（GET取得、POST作成、PATCH更新、DELETE削除）
  • JSON：データの書き方（送る/返る中身）
  • SQL：サーバーがDBに命令する言語
  • OpenAPI：上の全部を仕様書にしたもの

次にやると理解が爆速で固まること

理解を「知識」から「実装」に変える一番早い方法は、1本だけAPIを作って叩くことです。

おすすめは /me。

  • OpenAPIで定義された GET /me
  • 認証（Bearerトークン）
  • DBから user/profile を取得
  • JSONで返す（200）

この1本が通ると、他のAPIも同じ型で増やせます。

Discussion