API連携の始め方｜開発方法の選び方とPythonの実装例

天気や地図を表示する、外部サービスへデータを登録する、アプリ同士で情報を共有する。API連携を使うと、既存のサービスが提供する機能を、自分のアプリや業務に組み込めます。

API連携を始めるときは、連携する処理を一つに絞り、リクエスト・応答・失敗時の動作を順に確認することが大切です。データを一度取得できた後は、権限や料金、継続して運用するための仕組みも整えます。

この記事では、ノーコード、スクリプト、BaaSの使い分けと、Pythonで練習用APIを呼び出す例を紹介します。初めてAPI連携に取り組む方が、何から確認すればよいかを整理していきましょう。

１．API連携とは、決められた形式で機能やデータを利用すること

APIは、ソフトウェアの機能やデータを、別のプログラムから利用するための窓口です。この記事では、HTTP通信を使い、外部サービスへ処理を依頼するWeb APIを中心に扱います。

例えば、天気を表示するアプリなら、地域などの条件をAPIへ送り、返されたデータから必要な項目を取り出して表示します。提供元がデータを用意していても、入力の受付や画面表示、エラー時の対応は自分のアプリで実装します。

API連携によって既存機能を活用できますが、外部サービスの料金、利用制限、仕様変更にも対応する必要があります。導入の手軽さと、運用で必要な作業を合わせて考えましょう。

２．API連携の開発方法を選ぶ

API連携には、画面操作で設定する方法と、プログラムを書く方法があります。必要な機能や変更の頻度、運用する人に合わせて選ぶと、導入後も管理しやすくなります。

ノーコードでも、処理の条件は確認する

ノーコードツールでは、「データが追加されたら別のアプリへ通知する」といった処理を画面上で組み立てられる場合があります。ただし、連携先のすべての機能を使えるとは限りません。

例えば、新規登録には対応していても、更新や削除の同期には別の設定が必要なことがあります。処理が失敗したときの通知先や、再実行で同じデータが重複しないかも確認しましょう。

スクリプトでは、必要な処理を小さく作る

PythonやJavaScriptなどでAPIを呼び出すと、取得したデータの加工や、独自の判定を組み込めます。公式SDKがある場合は、対応機能と使い方を確認したうえで利用を検討してください。

最初から複数のサービスをつなぐより、一つのAPIから一件のデータを取得する処理から始めましょう。入力と出力が分かれば、どの段階で問題が起きたかを調べやすくなります。

BaaSを使っても、アクセス権限の設計は必要

BaaSは、認証、データベース、ファイル保存などの機能をサービスとして利用する方法です。サーバー構築の一部を任せられますが、SDKを読み込むだけで安全な公開設定が完成するわけではありません。

例えば、Supabaseのフロントエンド向けデータアクセスでは、公開用キーに加えて、Row Level Security（RLS）による適切なアクセス制御が必要です。管理用の秘密キーをブラウザへ配信しないことも、利用者側で確認します。

３．公式ドキュメントで、最初に確認する項目

APIを選んだら、コードを書く前に、呼び出し方と返されるデータを確認します。サンプルコードをコピーするだけでなく、どの値を自分の用途に合わせる必要があるかを整理してください。

JSONは、APIのデータ交換によく使われる形式の一つです。ただし、すべてのAPIがJSONを返すわけではなく、成功時とエラー時で応答形式が異なる場合もあります。

また、APIキーが何を識別するかはサービスによって異なります。アプリ利用者本人のログインや、個々のデータへのアクセス許可まで、キーだけで管理できるとは限りません。

４．Pythonで練習用APIからデータを取得する

ここでは、学習や試作向けの架空データを提供する「JSONPlaceholder」を使います。今回の取得処理にはアカウント登録やAPIキーが不要なため、通信と応答の扱いを確認できます。

このサービスは、実際の業務データを保存するためのものではありません。登録や更新のAPIも用意されていますが、変更が実際に保存されるわけではない点に注意してください。

Requestsをインストールする

Pythonを利用できる環境で、次のコマンドを実行します。ほかの開発環境と依存関係を分けたい場合は、プロジェクト用の仮想環境を作成してからインストールしてください。

python -m pip install requests

データの取得と確認を行う

次のコードをapi_example.pyとして保存します。練習用のタスクを一件取得し、タイトルと完了状態を表示する例です。

import requests


def main():
    url = "https://jsonplaceholder.typicode.com/todos/1"

    try:
        response = requests.get(url, timeout=(3, 10))
        response.raise_for_status()
        data = response.json()
    except requests.exceptions.Timeout:
        print("通信がタイムアウトしました。")
        return
    except requests.exceptions.HTTPError as error:
        print(f"HTTPエラー: {error.response.status_code}")
        return
    except requests.exceptions.JSONDecodeError:
        print("JSONとして読み取れない応答でした。")
        return
    except requests.exceptions.RequestException:
        print("通信に失敗しました。接続状況を確認してください。")
        return

    if not isinstance(data, dict):
        print("想定したデータ構造ではありません。")
        return

    if (
        not isinstance(data.get("title"), str)
        or not isinstance(data.get("completed"), bool)
    ):
        print("必要な項目がないか、値の型が異なります。")
        return

    print(f"タイトル: {data['title']}")
    print("状態:", "完了" if data["completed"] else "未完了")


if __name__ == "__main__":
    main()

保存したファイルがある場所で、次のコマンドを実行します。正常にデータを取得できれば、タスクのタイトルと状態が表示されます。

python api_example.py

コードで確認していること

raise_for_status()は、HTTPの4xx・5xxエラーを例外として扱います。続くresponse.json()は応答をJSONとして読み取り、その後で必要な項目と型を確認しています。

JSONとして読み取れたことだけでは、処理が成功したとは限りません。エラー内容がJSONで返されるAPIもあるため、HTTPステータスと応答内容の両方を確認します。

timeout=(3, 10)は、接続の待ち時間と読み取りの待ち時間を指定しています。プログラム全体を必ず13秒以内に終了させる設定ではなく、今回の値もすべてのAPIに適した基準ではありません。

この例では、自動で再試行せず、失敗した段階を表示して終了します。別のAPIへ変更する場合は、URLだけでなく、認証方法、必要な入力、返される項目も変更してください。

５．実際のサービスへつなぐときに追加する設定

練習用APIで流れを確認できたら、利用したいサービスの設定へ進みます。認証情報の発行、アクセス権限、利用量の管理は、サービスの公式手順に従って設定してください。

秘密の認証情報は、配信するコードに含めない

秘密として扱うAPIキーやトークンは、公開リポジトリやブラウザへ配信するJavaScriptに含めません。サーバー側の環境変数やシークレット管理機能を使い、ログにも出力しないようにします。

.envは設定値を置くファイルであり、自動的に秘密を保護する仕組みではありません。フロントエンドのビルド時に値を読み込み、配信するコードへ埋め込んだ場合は、利用者から確認できる状態になります。

アクセスできる範囲を絞る

データの閲覧だけが必要なら、更新や削除まで許可する必要があるかを確認します。また、外部APIへの権限とは別に、自分のアプリで誰がその機能を利用できるかも管理してください。

例えば、生徒が自分の学習記録を確認する機能では、別の生徒のIDを指定しても記録を取得できないようにします。外部サービスへ接続できることと、アプリ利用者へ何を許可するかは別の設計です。

管理画面の設定と、実行環境を一致させる

GoogleのAPIなどでは、対象プロジェクトでのAPI有効化や、認証情報の制限設定が必要になる場合があります。開発環境と本番環境でURLや認証情報が異なる場合は、それぞれ確認しましょう。

設定を変える際は、対象プロジェクトやアカウントを確認します。動かない原因を調べずに、アクセス制限を外したり、広い権限を追加したりしないことが大切です。

６．APIが失敗したときの扱いを決める

外部APIは、通信障害、権限不足、入力の誤り、利用上限などで失敗します。すべて同じ方法で再試行せず、返された情報と、その操作がデータを変更するかどうかを確認してください。

登録や決済は、安易に再送しない

タイムアウトしても、相手側では登録や決済が完了している場合があります。同じ依頼をそのまま送り直すと、二重処理になる可能性があるため、処理結果の照会方法や重複防止の仕様を確認します。

提供元が冪等性キーなどの仕組みを用意している場合は、その使い方に従います。再試行する処理には回数の上限を設け、SDKの自動再試行と重複していないかも確認してください。

代わりに表示するデータにも条件を付ける

取得に失敗した際、以前取得したデータを表示する方法もあります。ただし、保存が利用規約で認められているか、古い情報を表示してもよい用途かを確認してください。

過去のデータを表示する場合は、取得日時や更新できていないことを示します。現在の在庫や処理結果など、最新であることが必要な情報を、確認済みのように表示しないようにしましょう。

７．小さな検証から、継続して使える連携へ進める

一件のデータを取得できたら、条件を変えた入力や、結果が空になる場合も確認します。その後、公開時に必要な権限、利用量、監視方法を整えていきましょう。

記録する内容も、目的に合わせて決めます。処理の成功・失敗、応答時間、呼び出し回数などは運用の判断材料になりますが、秘密情報や不要な個人情報を丸ごと保存しないようにしてください。

• 連携する処理と、成功と判断する条件が決まっている。
• 必要な入力と、応答の項目・型を確認している。
• 認証情報の保管場所と、アクセス権限を確認している。
• 料金と利用上限を確認し、呼び出し量を把握できる。
• タイムアウトや失敗時の表示・再試行方針が決まっている。
• 登録や更新が重複しないかを確認している。
• 仕様変更や提供終了の案内を確認する担当が決まっている。

API連携を手軽に始めるには、最初の範囲を小さくすることが役立ちます。まず一つの処理で、送る内容と返される結果を理解し、その確認を積み重ねながら機能を広げてください。

参考資料

• JSONPlaceholder：練習・試作用のAPIと利用ガイド
• Requests：Quickstart
• Requests：Advanced Usage（タイムアウトなど）
• Supabase：Securing your data