システム開発入門の第22週目は、外部APIとの連携がテーマです。前週までに学んだPythonを使い、別のサービスへ情報を要求し、返ってきたデータから必要な値を取り出す流れを実習しました。
外部API連携では、コードを書く前に通信の順序を理解する必要があります。今回の授業では、HTTP、エンドポイント、JSON、ステータスコード、APIキーを一つの流れとして整理しました。
API連携は「要求」と「応答」の組み合わせ
APIは、プログラム同士が機能やデータをやり取りするための窓口とルールです。授業では、先生が「APIは読み書きのルール」と説明し、ブラウザやプログラムからURLへ要求を送り、サーバーがJSONを返す流れを図で確認しました。
| 段階 | 行うこと | 確認するもの |
|---|---|---|
| 要求を作る | 利用したい機能のURLと操作方法を決める | HTTPメソッド、エンドポイント、パラメータ、認証 |
| 要求を送る | プログラムから外部サービスへリクエストを送る | 送信先と送信内容 |
| 応答を受け取る | サーバーから返った結果を受け取る | ステータスコードとレスポンス本文 |
| 必要な値を使う | JSONの構造をたどり、必要なデータを取り出す | キー、配列の位置、値の形式 |
授業で整理した五つの用語
- HTTP
- クライアントとサーバーが要求と応答をやり取りするときの仕組みです。今回の実習では、情報を取得するGETと、情報を送るPOSTを学びました。
- エンドポイント
- APIの機能ごとに用意されたアクセス先のURLです。同じサービスでも、取得したい情報や実行したい操作によって窓口が変わります。
- JSON
- データをキーと値の組み合わせや配列で表す形式です。階層がある場合は、外側から順にキーや配列の位置をたどります。
- ステータスコード
- リクエストの結果を数字で伝える情報です。本文を読む前に、要求が成功したか、認証や送信先に問題があるかを判断する手掛かりになります。
- APIキー
- サービスによって求められる認証情報です。ソースコードや公開リポジトリへ書き込まず、利用するAPIの説明に従って管理します。
これらは別々の暗記事項ではありません。エンドポイントへHTTPリクエストを送り、ステータスコードを確認し、JSONから必要な値を読むという一連の処理を構成しています。
PythonでGETリクエストを読む
実習では、外部サービスから天気情報を取得する想定の疑似コードを使いました。URLとAPIキーは学習用の仮の値であり、そのまま実行するコードではありません。
import requests
url = "https://api.example.com/weather"
params = {"q": "Tokyo", "appid": "YOUR_API_KEY"}
response = requests.get(url, params=params)
if response.status_code == 200:
data = response.json()
temp = data["main"]["temp"]
description = data["weather"][0]["description"]
print(f"現在の気温：{temp}℃、天気：{description}")
else:
print(f"エラーが発生しました：{response.status_code}")
コードを追う順序
urlにアクセス先のエンドポイントを設定します。paramsに検索条件とAPIキーをまとめます。requests.get()でGETリクエストを送ります。response.status_codeが200なら、response.json()で応答をPythonから扱える形に変換します。data["main"]["temp"]のようにキーを順番に指定し、必要な値を取り出します。
data["weather"][0]["description"]では、weatherの中にある配列の先頭を選び、その中のdescriptionを読んでいます。JSONの階層を一度に理解しようとせず、外側から一段ずつ確認すると、取り出す場所を見つけやすくなります。
実際のAPIでは、利用できるエンドポイント、パラメータ、認証方法、返されるJSONの構造がサービスごとに異なります。コードを書く前に公式ドキュメントで確認することが、実習の出発点です。
ステータスコードから失敗の理由を分ける
「動かなかった」で終わらせず、返されたステータスコードから確認先を分けることも今回の課題でした。
| コード | 授業での意味 | 最初に確認すること |
|---|---|---|
| 200 | 成功 | 返されたJSONから必要な値を取り出せるか |
| 401 | 認証エラー | APIキーと認証方法が正しいか |
| 404 | 見つからない | エンドポイントや指定した対象が正しいか |
ステータスコードだけで処理を完了できるわけではありません。まず結果を分類し、APIのドキュメントとレスポンス本文を照らし合わせて、次に直す場所を決めます。
ハンズオン課題の進め方
生徒たちは、学校のネットワークポリシーに従い、利用できるAPIを選んで次の手順に取り組みました。
- APIドキュメントを読み、利用するエンドポイントを一つ決める。
- 必要なパラメータと認証方法をメモする。
requests.get()でデータを取得する。- 返されたJSONの構造を確認し、表示したい値までの経路を特定する。
- ステータスコードに応じた表示を用意し、失敗時にも状況を確認できるようにする。
課題で難しかったのは、コードの入力よりもドキュメントとJSONの階層を読む作業でした。しかし、エンドポイント、パラメータ、応答の構造を順に分けると、どこで迷っているかを確認できます。
APIを安全に利用するための確認事項
- APIキーを公開しない：公開リポジトリへ置かず、
.envなどを使ってソースコードから分けて管理します。 - レート制限を確認する：一定時間に利用できる回数をドキュメントで確認し、その範囲でリクエストを送ります。
- 利用規約を読む：商用利用や取得データの二次配布が認められているかを、利用前に確認します。
外部APIは、自分のプログラムの外にある機能やデータを利用する仕組みです。そのため、コードが動くことだけでなく、提供側のルールを守り、失敗時の動作まで考える必要があります。
第22週目の到達点と次回の課題
今回の授業では、外部API連携を「URLへアクセスする処理」だけで捉えず、要求を作る、応答を確認する、JSONを読む、失敗の理由を分けるという手順で理解しました。
次週は、この流れを使った小さなAPI連携プロジェクトに進む予定です。天気情報を取得して表示するミニアプリを例に、設計、実装、エラー処理までを一続きで経験します。
関連する授業と解説
この記事に関連する株式会社greedenの取り組み
外部API連携は、通信できるだけでなく、認証や例外処理まで設計して初めて安定して使えます。株式会社greedenは、業務要件に応じたWebシステムの設計と実装、API開発と外部サービス連携を一気通貫で支援しています。