API設計・開発・連携の基本｜認証と認可、仕様書、エラー処理を整理する
Webアプリや外部サービスを連携するとき、APIはデータや機能をやり取りする窓口になります。しかし、動作することだけを優先すると、仕様変更やエラーへの対応で、後から手間が増えることがあります。
使いやすいAPIを作るには、操作の意味、データの形式、アクセス権限、失敗した場合の扱いを整理することが大切です。この記事では、HTTP APIの設計から実装、外部サービスとの連携まで、確認しておきたい基本を紹介します。
目次
１．API設計では「誰が、何をするか」を先に決める
最初に、APIを使う人やシステムと、必要な操作を整理します。画面に表示する情報だけでなく、「誰が閲覧できるか」「誰が変更できるか」も、設計段階で決めておきましょう。
例えば、学習記録を扱うアプリなら、生徒は自分の記録を確認し、講師は担当する生徒の記録を確認する、といった違いがあります。同じデータでも、利用者によって許可する操作が変わります。
| 設計する項目 | 学習記録アプリでの例 |
|---|---|
| 操作対象 | 学習記録、教材、課題 |
| 必要な操作 | 一覧取得、登録、修正、削除 |
| 利用者 | 生徒、講師、管理者 |
| アクセス範囲 | 自分の記録、担当する生徒の記録 |
| 入力条件 | 学習時間は０以上、教材IDは存在するもの |
この段階で具体例を作っておくと、画面側とサーバー側の認識を合わせやすくなります。正常に使う場面だけでなく、入力ミスや権限不足の場合も考えておきましょう。
２．URLとHTTPメソッドの役割をそろえる
リソースを中心に設計するAPIでは、URLで操作対象を示し、HTTPメソッドで操作の意味を表す方法がよく使われます。例えば、学習記録なら次のように整理できます。
| 操作 | 設計例 |
|---|---|
| 学習記録の一覧を取得する | GET /study-records |
| 新しい学習記録を登録する | POST /study-records |
| 特定の学習記録を取得する | GET /study-records/123 |
| 特定の学習記録を削除する | DELETE /study-records/123 |
ただし、「URLに動詞を含めてはいけない」「必ず複数形にする」という絶対的な規則ではありません。対象となる操作に合う表現を選び、同じAPIの中で命名方針をそろえることが重要です。
HTTPメソッドには、それぞれ意味があります。例えばGETは情報の取得を目的とするため、GETへのアクセスによって利用者のデータを削除するような設計は避けてください。URLの見た目だけでなく、メソッドに期待される動作を守りましょう。
３．認証・認可・トークンの形式を区別する
認証は、利用者や接続元が誰であるかを確認することです。認可は、その利用者や接続元に、どのデータへのアクセスや操作を許可するかを判断することです。
APIの説明では、OAuth 2.0、OpenID Connect、JWT、APIキーが登場します。ただし、これらはすべて同じ役割を持つものではありません。
| 用語 | 主な役割・位置付け |
|---|---|
| OAuth 2.0 | アプリに限定的なアクセス権を与えるための認可の枠組み |
| OpenID Connect | OAuth 2.0を基盤に、利用者の認証情報を扱う仕組み |
| JWT | 発行者や有効期限などの情報を表現するトークンの形式 |
| APIキー | サービスの仕様に応じて、接続元の識別や利用管理などに使う値 |
OAuth 2.0を導入しただけで、利用者のログイン認証が完成するとは限りません。ログイン連携を作る場合は、OpenID Connectなど、提供元が案内する認証の仕組みを確認します。
また、JWTはOAuth 2.0と二者択一になるものではありません。OAuthで使うアクセストークンがJWT形式の場合もあれば、内部情報を読み取れない別の形式の場合もあります。採用するサービスの仕様に従って扱いましょう。
JWTは、読み取れたら信用してよいわけではない
署名されたJWTでも、暗号化されていなければ中身を読み取れます。署名による改ざん検出と、暗号化によって内容を隠すことは別の機能です。パスワードなど、漏れてはいけない情報を安易に入れないようにしてください。
受け取ったJWTは、内容をデコードするだけでは不十分です。用途に応じて署名、許可したアルゴリズム、発行者、対象となるサービス、有効期限などを検証します。自作の判定処理を増やす前に、公式SDKや保守されているライブラリの設定を確認しましょう。
ログイン済みでも、データごとの権限確認は必要
例えば、URLの番号を変えるだけで、他の生徒の学習記録を取得できてしまう設計は問題です。ログイン済みかどうかに加えて、その記録を閲覧・変更する権限があるかを、サーバー側で確認します。
画面上でボタンを隠すだけでは、APIへの直接アクセスを防げません。OWASPも、IDで指定されたデータを操作するAPIでは、対象データに対する権限確認が必要だと説明しています。
４．仕様書とモックで、実装前に認識を合わせる
APIの仕様書には、URLとメソッドだけでなく、入力項目、必須条件、応答の形式、認証・認可の条件、エラー時の動作も記録します。
OpenAPIは、HTTP APIの仕様を記述するための標準です。Swaggerは、その仕様の編集や表示などに使われるツール群の名称として使われます。仕様とツールを区別すると、導入時に整理しやすくなります。
仕様を先に書く方法と、実装から仕様書を生成する方法のどちらも選択肢になります。重要なのは、仕様変更と実装変更が対応し、利用者が現在の動作を確認できることです。
また、ダミーデータを返すモックを用意すると、サーバー側の実装を待たずに画面の開発を進められます。ただし、モックで動いたことは、本物のAPIでも権限確認やエラー処理が正しく動くことの証明にはなりません。
５．成功時と失敗時の応答を決める
APIを利用する側が次の処理を判断できるよう、HTTPステータスコードと応答内容を整えます。すべてを200で返し、本文の文字列だけで成否を判定させる設計は、利用側を複雑にしやすくなります。
| ステータスコード | 主な意味 |
|---|---|
| 200 | リクエストが成功した |
| 201 | リクエストによって新しいリソースが作成された |
| 400 | 不正な要求など、クライアント側の問題で処理できない |
| 401 | 対象への有効な認証情報がない |
| 403 | 要求を理解したが、処理を拒否した |
| 404 | 対象が見つからない、または存在を開示しない |
| 500 | サーバー側で予期しない問題が発生した |
具体的な使い分けはHTTPの仕様とAPIの設計方針に沿って決めます。成功時と失敗時のJSONを同じ形にすること自体が目的ではなく、利用側が一貫した方法で解釈できることが大切です。
エラー応答には、問題を特定できるコードや、修正可能な入力項目などを含めます。一方、認証情報、内部の接続設定、詳細なスタックトレースを、そのまま外部に返さないようにしましょう。
６．外部APIの再試行では、二重処理を防ぐ
外部APIとの通信では、利用制限や一時的な障害に備えます。429は一定時間内の要求が多すぎることを示すステータスで、再試行までの待機時間を示すRetry-Afterが付く場合があります。提供元の仕様を確認して対応してください。
再試行する場合は、回数や待機時間に上限を設けます。待ち時間を徐々に長くし、必要に応じてばらつきを加える方法もありますが、すべてのエラーを繰り返せばよいわけではありません。
特に、登録・投稿・決済では注意が必要です。通信がタイムアウトしても、相手側では処理が完了している可能性があります。そのまま再送すると、同じ処理が二重に行われることがあります。
提供元が対応していれば冪等性キーを使い、同じ処理要求を識別できるようにします。対応していない場合も、処理結果を照会するなど、再送してよいか判断する方法を設計しましょう。HTTPの仕様でも、冪等でない要求の自動再試行には条件が必要とされています。
７．変更と性能改善は、利用状況を見て進める
APIを公開した後は、項目名や型の変更、項目の削除、必須入力の追加などが、利用側に影響します。変更前に影響を調べ、必要に応じて移行期間や旧仕様の終了日を案内してください。
URLに「v1」を付ける方法は、バージョン管理の選択肢の一つです。ただし、番号を付けるだけで互換性が保たれるわけではありません。どの変更を既存バージョンで許可するかも決めておきましょう。
性能を改善するときは、まず処理時間やデータ量を計測します。データベースへの問い合わせ、外部サービスへの通信、返す項目数などを調べ、遅くなっている箇所に対応します。
一度に多くのデータを返す設計が、常に悪いわけではありません。通信回数を減らせる利点もあるため、取得件数の上限、ページ分割、応答サイズ、サーバーの負荷を踏まえて判断してください。
８．実装後は、失敗する条件も確認する
正常な入力で動くことを確認したら、不正な入力や権限不足の場面も確認します。特に、他人のデータへアクセスできないことや、再試行しても二重登録されないことは、具体的なケースで検証しましょう。
| 確認する場面 | 確認したいこと |
|---|---|
| 必須項目がない | 適切なエラーを返すか |
| トークンが無効・期限切れ | 保護された処理を実行しないか |
| 他人のデータIDを指定する | 権限のない閲覧・変更を拒否するか |
| 同じ要求を再送する | 二重処理への対策が機能するか |
| 外部APIが応答しない | 無制限に待機・再試行しないか |
API開発では、URLの形を整えるだけでなく、入力から権限確認、処理結果、失敗時の対応までをつなげて考えることが必要です。まず一つの操作を設計し、利用側が迷わず扱えるかを確認しながら、機能を広げていきましょう。
Learning Tools
記事を検索したい方はここから！
記事を検索
関連記事や、今の内容に近いテーマをすぐに検索できます。
例: AI / 情報Ⅰ / Python / 統計 / 資格 / 学習法