APIとは何か
このページで学ぶこと
Section titled “このページで学ぶこと”- APIを「システム同士の決められた窓口」として捉える方法
- Web APIでリクエストとレスポンスがどのように行き来するか
- REST、リソース、エンドポイント、JSON、HTTPメソッドの基本
- ブラウザ・フロントエンド・サーバー・外部サービスの役割
- APIを使うことで増える制作・運用上の確認事項
API（Application Programming Interface）は、あるシステムの機能やデータを、別のシステムから利用するための決められた窓口です。
flowchart LR
U[利用者] --> W[Webサイト]
W -->|決められた形式で要求| A[API]
A --> S[外部サービス・業務システム]
S --> A
A -->|決められた形式で結果| W
W --> U
利用側は、相手システム内部の作り方をすべて知らなくても、公開された仕様に従って機能やデータを利用できます。
たとえばWebサイトから、次のような処理を行うときにAPIが使われます。
- CMSから記事を取得する
- 施設情報を検索する
- 地図や経路を表示する
- 在庫や予約枠を確認する
- 問い合わせをCRMへ登録する
- 会員情報を取得する
- 決済サービスへ処理を依頼する
- 分析サービスへイベントを送る
APIは「画面」ではなく「システム向けの窓口」
Section titled “APIは「画面」ではなく「システム向けの窓口」”人間は管理画面やWebページを操作します。
プログラムはAPIを通して、決められた名前・URL・データ形式で処理を依頼します。
flowchart TD
H[人間] --> UI[管理画面・Web画面]
P[別システム] --> API[API]
UI --> CORE[サービス内部の機能・データ]
API --> CORE
管理画面とAPIが、同じ内部データを使うこともあります。
ただし、管理画面でできることとAPIでできることが完全に同じとは限りません。APIでは参照だけ可能、削除は不可、取得件数に上限があるなど、別の権限・制限を持つ場合があります。
Web APIの基本：リクエストとレスポンス
Section titled “Web APIの基本：リクエストとレスポンス”Web APIでは、利用側がHTTPを使って要求を送り、提供側が結果を返す形が一般的です。
sequenceDiagram
participant F as Webサイト
participant A as API
participant D as データ
F->>A: リクエスト
A->>D: 必要なデータ・処理を確認
D-->>A: 結果
A-->>F: レスポンス
リクエストには、主に次の情報が含まれます。
- どのAPIへ送るか
- 何を取得・作成・変更・削除したいか
- 検索条件や入力内容
- 認証情報
- 受け取りたい形式
レスポンスには、主に次が含まれます。
- 成功・失敗を示す状態
- 取得したデータ
- 作成・変更の結果
- エラー内容
- 次ページ取得等の補助情報
エンドポイントとは
Section titled “エンドポイントとは”エンドポイントは、APIの具体的な窓口となるURLです。
たとえば概念的には、次のような窓口が考えられます。
- 記事一覧を取得する窓口
- 一つの記事を取得する窓口
- 予約を登録する窓口
- 会員情報を更新する窓口
実際のURLや入力方法はAPI仕様書で定義されます。
PMはAPIのコードを読む必要はありませんが、機能ごとにどの窓口を使い、何を送受信するかは把握します。
REST APIとは
Section titled “REST APIとは”REST APIは、Webで広く使われる設計原則に沿ったAPIです。
RESTでは、記事、商品、利用者、予約などの対象をリソースとして捉え、URLとHTTPの操作を使って扱います。
flowchart LR
C[利用側] --> R1[記事リソース]
C --> R2[施設リソース]
C --> R3[予約リソース]
RESTは製品名や通信形式の名前ではありません。
すべてのWeb APIが厳密なREST設計というわけではありませんが、実務では「HTTPとJSONを使う一般的なWeb API」という広い意味でREST APIと呼ばれる場合もあります。
HTTPメソッド
Section titled “HTTPメソッド”HTTPメソッドは、そのリソースに対して何を行いたいかを示します。
| メソッド | 一般的な用途 | Web制作での例 |
|---|---|---|
| GET | 取得 | 記事一覧、施設詳細を取得 |
| POST | 作成・処理実行 | 問い合わせ、予約を登録 |
| PUT | 全体を更新 | 一件の情報を置き換える |
| PATCH | 一部を更新 | 公開状態や項目を変更 |
| DELETE | 削除 | 下書きや登録情報を削除 |
実際のAPIがこの通りに設計されているとは限りません。仕様書を確認します。
PMがメソッド名を暗記することより、参照だけか、データを変更する処理かを区別することが重要です。
データを変更するAPIでは、誤送信、二重送信、権限、監査ログ、取消方法等の確認が増えます。
JSONとは
Section titled “JSONとは”JSON（JavaScript Object Notation）は、データを項目名と値の組み合わせで表す形式です。
APIでは、たとえば次のような情報を返せます。
- 記事タイトル
- 公開日時
- 本文
- 画像URL
- カテゴリ
- 著者
- 公開状態
JSONは画面の見た目を持ちません。
受け取ったデータを、Webサイト側のHTML・CSS・JavaScriptが表示へ変換します。
flowchart LR
C[CMS] -->|JSONデータ| F[フロントエンド]
F -->|HTMLとして構成| P[Webページ]
この分離によって、同じデータをWebサイト、アプリ、デジタルサイネージ等へ再利用できます。
一方、データだけではレイアウトや公開経路が完成しないため、表示側の開発が必要です。
API仕様書に書かれること
Section titled “API仕様書に書かれること”API仕様書には、通常次のような情報が記載されます。
- APIの目的
- エンドポイント
- HTTPメソッド
- 入力項目
- 必須・任意
- データ型・文字数
- レスポンス形式
- エラー
- 認証方法
- 利用制限
- サンプル
- バージョン
- 更新履歴
OpenAPIという標準形式で、HTTP APIの仕様を人間とツールが読める形に記述することもあります。
仕様書が存在しても、最新状態と実装が一致しているか、例外条件まで記載されているかを確認します。
APIを使う側と提供する側
Section titled “APIを使う側と提供する側”API連携には、少なくとも二つの立場があります。
API提供側
Section titled “API提供側”- 仕様を定める
- データ・機能を返す
- 認証・制限を行う
- 障害・変更を通知する
- 利用状況を監視する
API利用側
Section titled “API利用側”- 仕様に沿って呼び出す
- 入力内容を整える
- 結果を画面へ表示する
- エラー・遅延へ対応する
- 認証情報を管理する
- 変更へ追従する
制作会社が利用側、クライアントの基幹システム担当が提供側になる案件もあります。
API事業者が外部企業の場合、制作会社だけで仕様変更や障害を直すことはできません。
ブラウザから直接呼ぶ場合とサーバー経由の場合
Section titled “ブラウザから直接呼ぶ場合とサーバー経由の場合”APIの呼び出し場所によって、構成と安全性が変わります。
ブラウザから直接呼ぶ
Section titled “ブラウザから直接呼ぶ”flowchart LR
B[ブラウザ] --> A[外部API]
- 利用者の端末からAPIへ通信する
- 即時にデータを取得しやすい
- 秘密情報をブラウザへ置けない
- CORSの許可が必要になる場合がある
- API障害が画面に直接影響する
- 利用量制御が難しい場合がある
サーバー・サーバーレス処理を経由する
Section titled “サーバー・サーバーレス処理を経由する”flowchart LR
B[ブラウザ] --> S[自社サーバー・関数]
S --> A[外部API]
- 秘密キーをサーバー側で管理できる
- 入力検証やデータ加工を行える
- キャッシュ・再試行・監視をまとめやすい
- サーバー側処理の構築・運用が必要
- 経由地点の障害・費用が増える
どちらが常に正しいわけではありません。
APIの公開範囲、認証、データ、利用量、表示速度、個人情報等に応じて決めます。
APIとWebhookの違い
Section titled “APIとWebhookの違い”通常のAPI取得では、利用側が必要なタイミングで情報を取りに行きます。
Webhookでは、提供側で更新等が起きたとき、あらかじめ登録されたURLへ通知します。
flowchart LR
C[CMSで記事公開] -->|Webhook通知| B[ビルド・連携処理]
B --> W[Webサイトを更新]
ヘッドレスCMSの記事公開をきっかけにビルドを開始する、決済完了をきっかけに注文状態を更新する、といった用途があります。
Webhookは変更内容そのものをすべて送る場合と、「変更があった」という通知だけを送る場合があります。
通知の失敗、再送、重複、認証、順序を設計します。
APIを使うメリット
Section titled “APIを使うメリット”既存機能を利用できる
Section titled “既存機能を利用できる”地図、決済、検索、認証等をすべて自社開発せずに利用できます。
システムを分離できる
Section titled “システムを分離できる”CMS、Webサイト、業務システム等を独立して開発・更新できます。
データを複数チャネルへ使える
Section titled “データを複数チャネルへ使える”Web、アプリ、サイネージ、メール等で共通データを利用できます。
自動化できる
Section titled “自動化できる”手作業の転記やCSV受け渡しを減らせます。
APIを使うことで増えるもの
Section titled “APIを使うことで増えるもの”- 仕様確認
- 認証・権限
- 外部通信
- エラー・タイムアウト
- 利用制限
- 費用
- 障害点
- 監視
- 仕様変更対応
- テスト環境
- データ責任
- 契約・規約
APIは連携を簡単にしますが、連携先への依存も増やします。
実案件ではどう考えるか
Section titled “実案件ではどう考えるか”ヘッドレスCMSから記事を取得する
Section titled “ヘッドレスCMSから記事を取得する”記事一覧、詳細、カテゴリ、画像、公開日時等をAPIから取得します。
PMは次を確認します。
- どの項目をCMSで管理するか
- 公開・下書きの扱い
- 一回に取得できる件数
- ページング
- APIキーの公開可否
- CMS障害時の表示
- 更新から反映までの経路
施設検索APIを利用する
Section titled “施設検索APIを利用する”住所・条件・現在地等を送り、該当施設を取得します。
- 検索条件の定義
- 0件・大量件数
- 緯度経度
- 表示順
- データ更新頻度
- 応答時間
- 障害時の案内
が画面仕様へ影響します。
問い合わせをCRMへ登録する
Section titled “問い合わせをCRMへ登録する”フォーム送信後に外部システムへ登録する場合、単にAPIを呼ぶだけではありません。
- 入力検証
- 二重送信
- 登録失敗
- メールだけ成功
- APIだけ成功
- 再送
- 個人情報
- 利用者へ見せる結果
を設計します。
PMチェックリスト
Section titled “PMチェックリスト”- APIで実現する目的を説明できる
- APIの提供者・利用者・契約者を把握している
- 仕様書と更新履歴を入手している
- 取得・作成・変更・削除のどれを行うか整理している
- 送受信する項目・必須条件を整理している
- ブラウザから直接呼ぶか、サーバーを経由するか確認している
- 秘密情報をブラウザへ置いていない
- API障害・遅延・空データ時の表示を決めている
- Webhookの失敗・重複・再送を考慮している
- APIの変更・終了時の担当を決めている
- データの正しさを誰が保証するか決めている
よくある誤解・失敗
Section titled “よくある誤解・失敗”「APIがあれば簡単に連携できる」
Section titled “「APIがあれば簡単に連携できる」”APIが存在しても、必要な項目・検索・更新・認証・制限が揃っているとは限りません。
「APIはデータベースへ直接接続する仕組み」
Section titled “「APIはデータベースへ直接接続する仕組み」”多くの場合、APIは内部のデータや処理を安全に公開する窓口です。利用側がデータベース構造を直接扱う必要はありません。
「JSONを受け取れば画面が完成する」
Section titled “「JSONを受け取れば画面が完成する」”JSONはデータです。HTMLへの変換、レイアウト、エラー、読み込み中、SEO、アクセシビリティ等を表示側で作ります。
「公開APIキーなら何に使われても問題ない」
Section titled “「公開APIキーなら何に使われても問題ない」”ブラウザ公開を想定したキーでも、利用元制限、権限、利用量、料金への影響を確認します。
「API連携は一度動けば終わり」
Section titled “「API連携は一度動けば終わり」”提供側の仕様変更、認証変更、データ追加、廃止、料金改定等への継続対応が必要です。
理解度チェック
Section titled “理解度チェック”Q1. APIを、非技術者へどのように説明しますか。
Section titled “Q1. APIを、非技術者へどのように説明しますか。”回答と解説
別システムの機能やデータを、決められた窓口・手順・形式で利用する仕組みと説明できます。Q2. JSONを取得できれば、そのまま利用者へWebページとして見せられるでしょうか。
Section titled “Q2. JSONを取得できれば、そのまま利用者へWebページとして見せられるでしょうか。”回答と解説
通常は表示側の実装が必要です。JSONの項目をHTMLへ組み立て、読み込み中・エラー・空データ等も設計します。Q3. 問い合わせフォームから外部CRMへ登録する場合、登録失敗時に何を決めますか。
Section titled “Q3. 問い合わせフォームから外部CRMへ登録する場合、登録失敗時に何を決めますか。”回答と解説
利用者への表示、再送、入力内容の一時保存、メール通知との整合、運用担当への通知、手動登録、個人情報の扱い等を決めます。Q4. ブラウザからAPIを直接呼ばず、サーバーを経由する主な理由は何ですか。
Section titled “Q4. ブラウザからAPIを直接呼ばず、サーバーを経由する主な理由は何ですか。”回答と解説
秘密キー管理、入力検証、データ加工、キャッシュ、監視、利用量制御等をサーバー側で行うためです。Q5. APIとWebhookの大きな違いは何ですか。
Section titled “Q5. APIとWebhookの大きな違いは何ですか。”回答と解説
通常のAPI利用は利用側から必要時に取りに行きます。Webhookは提供側の出来事をきっかけに、利用側へ通知します。- Google Cloud「REST API の基本と実装」
https://cloud.google.com/discover/what-is-rest-api?hl=ja
REST API、リソース、HTTPメソッド、リクエスト・レスポンスの全体像を確認するための公式解説。 - Google Cloud「API 設計ガイド」
https://docs.cloud.google.com/apis/design?hl=ja
ネットワークAPIの設計原則と用語を確認するための公式資料。 - OpenAPI Initiative「OpenAPI Specification」
https://spec.openapis.org/
HTTP APIを言語に依存せず記述する標準仕様の公式サイト。 - WordPress Developer Resources「REST API Handbook」
https://developer.wordpress.org/rest-api/
CMSがJSONでコンテンツを提供するAPIの具体例。