--- title: "API連携の実装方法：REST・認証・エラー処理の手順をcurlとPythonのコード例で解説" url: "https://www.issoh.co.jp/tech/details/15351/" published: 2026-07-18 updated: 2026-09-29 categories: ["REST API"] publisher: "株式会社一創" --- # API連携の実装方法：REST・認証・エラー処理の手順をcurlとPythonのコード例で解説 API連携の実装は、「方式の選定→仕様確認とAPIキー発行→呼び出し処理→認証→エラー処理→テストと公開」という手順に分解すると、着手の順番で迷わなくなります。この記事では、Web API連携の主流であるRESTを軸に、curlでの疎通確認、PythonによるHTTPリクエストの実装、APIキー・OAuth 2.0・JWTといった認証方式の使い分け、4xx/5xx応答の処理とリトライ設計、レート制限への対応、Webhookの受信、モックを使った検証までを実装者の目線で扱います。 各工程には、コピーしてそのまま動かせるコマンドとコード例を付けました。仕様の根拠はRFCや公式ドキュメントへその場でリンクしています。後半では、プログラミングで自前実装するか、連携ツールや受託開発に任せるかの判断基準も条件付きで整理します。 ## まとめ：API連携の実装方法は5ステップと3つの守りどころで決まる API連携の実装手順は5ステップに集約できます。①提供元のリファレンスでエンドポイント・データ形式・制限値を確認、②開発者登録とAPIキー発行、③テスト環境で疎通確認、④認証・呼び出し・エラー処理の本実装、⑤本番公開と監視です。連携方式は、相手先が指定している場合を除きREST＋JSONが第一候補になります。イベント発生時に相手から通知を受けたいならWebhookを併用します。 実装品質を分けるのは呼び出し部分ではなく、認証情報の管理とエラー処理です。次の3点を落とすと、鍵の漏えいや二重登録といった本番障害に直結します。 - **認証情報**：APIキーはサーバー側の環境変数か秘密情報管理の仕組みで保管し、ブラウザやアプリに埋め込まない - **再送**：リトライは冪等性を確かめてから入れる。POSTを送り直すなら冪等キーを付ける - **待機と打ち切り**：429応答にはRetry-Afterヘッダーに従って待ち、HTTPクライアントには必ずタイムアウトを設定する 小規模な定型連携なら連携ツール（iPaaS）で足ります。一方、業務ロジックが絡む連携や高い信頼性が要る連携は個別実装が必要です。その線引きは記事の後半で条件付きで示します。 ## API連携の実装方法の全体像｜方式選定から公開までの5つの基本手順 最初に、API連携のやり方の全体像をつかみます。実装作業そのものより先に決めるべき設計項目があり、ここを飛ばすと後工程の手戻りが大きくなるためです。方式の比較と5ステップの手順をこの章で押さえます。API連携そのものの意味やデータ連携・RPAとの違いから確認したい場合は、[API連携とは？仕組み・データ連携との違い・導入判断までわかりやすく解説](https://www.issoh.co.jp/column/details/15354/)で発注者向けに整理しています。 ### 実装前に確定させる設計項目｜連携方式・データ形式・同期タイミング コードを書く前に確定させるのは、連携方式（REST・SOAP・GraphQL・Webhookのどれか）、データ形式（JSONかXMLか）、同期タイミング（画面操作の都度呼ぶリアルタイム型か、夜間バッチでまとめて同期する型か）の3項目です。外部サービスと連携する場合、方式とデータ形式は提供元の仕様で決まっているため、選択の余地があるのは自社システム同士の連携です。 同期タイミングは業務要件から逆算します。在庫数のように鮮度が意味を持つデータはリアルタイム型、会計仕訳のように日次で締まるデータはバッチ型向きです。ここが曖昧なまま実装に入ると、呼び出し回数が想定を超えてレート制限に当たる、といった形で後から破綻します。 ### REST・SOAP・GraphQL・Webhook｜連携方式の比較と選定基準 Web API連携で使われる方式は次の4つに大別されます。 | 方式 | 通信の型 | 向く場面 | 補足 | | ------- | ----------- | ------------- | --------- | | REST | HTTPで資源を操作 | 汎用的なWeb API連携 | 現在の主流 | | SOAP | XMLメッセージ交換 | 金融・基幹系の既存接続 | 仕様が厳格で重い | | GraphQL | クエリで必要項目を取得 | 取得項目が画面ごとに変わる | 過剰取得を削れる | | Webhook | イベント時に相手が送信 | 決済完了などの通知受信 | 受信側の検証が必須 | 迷ったらRESTです。公開されているWeb APIの大半がRESTで提供されており、ライブラリとノウハウの蓄積量が他方式と桁違いだからです。設計原則やHTTPメソッドの使い分けは[RESTとは？REST APIの仕組みと6原則・SOAP/GraphQLとの違いを実装目線で解説](https://www.issoh.co.jp/tech/details/13588/)で詳細に整理しています。6原則のうちハイパーメディア制約をどこまで実装するかは[HATEOASの採用条件と見送る場面](https://www.issoh.co.jp/tech/details/16295/)で扱っています。 Webhookは単独で使うものではありません。RESTでの取得と組み合わせて「変化の通知だけ受けて、詳細はRESTで取りに行く」構成にすると、配信の取りこぼしや順序の入れ替わりに強くなります。受信側の実装は後の章で扱います。 ### API連携を実装する5ステップ｜仕様確認から本番公開までの流れ 実装の工程は次の順で進めます。 1. APIリファレンスでエンドポイント・データ形式・認証方式・レート制限を確認する 2. 提供元に開発者登録し、APIキーやクライアントIDを発行する 3. テスト環境（サンドボックス）で認証と疎通を確認する 4. 呼び出し処理・認証・エラー処理を本実装する 5. 本番のAPIキーに切り替えて公開し、監視とログを有効にする 工程で見落とされがちなのは1と3です。リファレンスの制限値（1分あたりの呼び出し上限や1回の取得件数上限）を読み飛ばすと、設計そのものが成立しないことがあります。またテスト環境を経由せず本番キーで開発すると、開発中の誤操作が実データに反映されかねません。提供元が審査制の場合、開発者登録から利用開始まで数日かかることもあるため、2は工程の早い段階で済ませます。 ## curlとPythonでAPIを呼び出す｜疎通確認からJSON処理までの実装 方式と手順が決まったら、呼び出し処理を実装します。この章はREST＋JSONを前提に、リファレンスの読み方、curlでの疎通確認、Pythonでの呼び出しの順に進めます。コード例のエンドポイントは説明用の架空のもので、実際の値は連携先のリファレンスに置き換えてください。どの言語でも考え方は共通です。 ### APIキーの発行とエンドポイント仕様の確認｜リファレンスの読み方 APIリファレンスで最初に確認するのは、ベースURLとエンドポイント一覧、各エンドポイントのHTTPメソッド、必須パラメータ、レスポンスのJSON構造、そしてエラーコード表です。読み方のコツは、正常系より先にエラーコード表と制限事項を読むことです。正常系はサンプルコードを写せば動きますが、エラー仕様は設計に跳ね返ります。 ページネーションの方式（ページ番号型かカーソル型か）と日時のタイムゾーン表記も、後から直すと影響範囲が広い代表例です。APIキーの発行は管理画面から行い、テスト用と本番用が分かれている場合は必ずテスト用から使い始めます。 ### curlで疎通を確かめる｜認証ヘッダーとステータスコードの確認手順 コードを書く前に、curlで1回呼んで「認証が通るか」「どんなJSONが返るか」を確かめます。ここで401や403が返るなら、コードの問題ではなくキーや権限の設定の問題だと切り分けることが可能です。トークンは環境変数に入れてから使い、コマンド履歴に残さないようにします。 ``` # トークンは環境変数から渡す（履歴に平文を残さない） export API_TOKEN="テスト用のトークン" curl -sS --max-time 10 \ -H "Authorization: Bearer ${API_TOKEN}" \ -H "Accept: application/json" \ -w "\nstatus=%{http_code} time=%{time_total}s\n" \ "https://api.example.com/v1/orders?limit=50" ``` `-w`でステータスコードと所要時間を末尾に出しておくと、応答本文と合わせて1回で状況がつかめます。`--max-time`を付けるのは、応答が返らないときに端末が固まるのを避けるためです。ステータスコードの一覧とcurl自体の終了コードの違いは[HTTPステータスコード一覧とcurlエラーコード一覧](https://www.issoh.co.jp/column/details/3038/)で引けます。 ### Pythonのrequestsで呼び出す｜タイムアウトとJSONの検証を入れた基本形 実装の基本形は、HTTPクライアントでリクエストを組み立て、ステータスコードで分岐し、JSONを自システムの型に変換する、という3段です。取得は`GET`、新規作成は`POST`、全体更新は`PUT`、削除は`DELETE`を使い、リクエストヘッダーに`Content-Type`と認証情報を付けます。HTTPメソッドとステータスコードの意味は[RFC 9110（HTTP Semantics・2022年6月発行）](https://www.rfc-editor.org/rfc/rfc9110.html)で定義されており、迷ったら一次情報にあたるのが確実です。 Pythonでは[requests](https://pypi.org/project/requests/)（2026年9月時点で2.34系）が定番です。[requestsの公式ドキュメント](https://requests.readthedocs.io/en/latest/user/advanced/)には「タイムアウトを明示しない限りリクエストはタイムアウトしない」と書かれており、`timeout`の指定は省略できません。接続と読み取りを分けたタプルで渡し、接続側はTCPの再送間隔である3秒の倍数より少し長くするのが同ドキュメントの推奨です。 ``` import os import requests BASE_URL = "https://api.example.com/v1" API_TOKEN = os.environ["API_TOKEN"] # ソースコードに直書きしない session = requests.Session() session.headers.update({ "Authorization": f"Bearer {API_TOKEN}", "Accept": "application/json", }) def list_orders(cursor=None): params = {"limit": 50} if cursor: params["cursor"] = cursor # (接続タイムアウト, 読み取りタイムアウト) を秒で指定する resp = session.get(f"{BASE_URL}/orders", params=params, timeout=(3.05, 10)) resp.raise_for_status() data = resp.json() # 外部の値は検証してから業務ロジックへ渡す items = data.get("items") or [] for item in items: item["amount"] = int(item["amount"]) # 数値が文字列で返る仕様への備え return items, data.get("next_cursor") ``` レスポンス処理で崩れやすいのは型変換です。JSONの数値が文字列で返る、null項目がキーごと省略される、といった仕様は珍しくありません。上の例のように、外部から受け取る値は必ず検証してから業務ロジックに渡します。カーソル型のページネーションなら、`next_cursor`が空になるまで同じ関数を呼び続ければ全件を取り切れます。 ## API連携の認証実装｜APIキー・OAuth 2.0・JWTを実装する手順 API連携のプログラミングで最初の関門になるのが認証です。方式はAPIキー・OAuth 2.0・JWTの3系統を押さえれば実務の大半を判断できます。どれを使うかは自分では選べないことが多く、提供元の指定に沿って正しく実装できるかが問われます。 ### APIキー認証の実装と管理｜漏えいを防ぐ保管と権限の絞り込み APIキー認証は、発行された固定の文字列をリクエストヘッダーに載せる方式で、実装は最も簡単です。そのぶん事故も単純で、キーの漏えいがそのまま不正利用になります。守るべき原則は3つあります。 - キーはソースコードに直書きせず、環境変数か秘密情報管理の仕組みに置く - ブラウザやモバイルアプリなどクライアント側に埋め込まず、必ず自社サーバー経由で呼ぶ - キーに付与する権限と参照範囲を必要最小限に絞る 公開リポジトリへのキー混入は今も定番の事故で、発生したら即時に無効化と再発行を行います。発行・保管・失効・ローテーションを仕組みとして回す方法は[APIキー管理とは？発行・保管・失効とローテーションの実装を解説](https://www.issoh.co.jp/tech/details/16300/)で、認証情報の窃取を含むAPI固有の攻撃経路は[APIセキュリティとは？OWASP API Top 10の主要リスクと実装対策を解説](https://www.issoh.co.jp/tech/details/13793/)で体系的に扱っています。 ### OAuth 2.0の認可コードフローを実装する｜PKCEとトークン交換の手順 ユーザーの代理でデータにアクセスする連携（例：利用者のカレンダーを読む）では、[OAuth 2.0（RFC 6749）](https://www.rfc-editor.org/rfc/rfc6749.html)の認可コードフローを実装します。手順は、認可画面へのリダイレクト→認可コードの受領→アクセストークンへの交換→トークンを付けてAPI呼び出し、という流れです。アクセストークンには有効期限があるため、リフレッシュトークンでの更新処理まで含めて初めて完成です。 2025年1月に発行された[OAuth 2.0のセキュリティBCP（RFC 9700）](https://www.rfc-editor.org/rfc/rfc9700.html)は、公開クライアント（ブラウザやスマホアプリ）にPKCEを必須とし、サーバー側で秘密を持てる機密クライアントにも推奨しています。これから実装するなら、最初からPKCE付きで組むのが安全側です。トークン交換のリクエストは次の形になります。 ``` # 認可コードをアクセストークンに交換する（サーバー側から送る） curl -sS --max-time 10 -X POST "https://auth.example.com/oauth/token" \ -u "${CLIENT_ID}:${CLIENT_SECRET}" \ -d grant_type=authorization_code \ -d code="${AUTH_CODE}" \ -d redirect_uri="https://app.example.com/callback" \ -d code_verifier="${CODE_VERIFIER}" # 応答例：access_token・expires_in・refresh_token を受け取り、 # access_token は Authorization: Bearer ヘッダーに載せて使う ``` `code_verifier`は認可リクエストの前に生成した乱数で、そのハッシュ値を認可リクエストに付けておきます。交換時に元の値を送ることで、途中で認可コードを盗まれても第三者はトークンに交換できません。認可フローの種類とOAuth 2.1での変更点は[OAuth 2.0とは？仕組み・認可フローと認証との違い、OAuth 2.1の変更点](https://www.issoh.co.jp/tech/details/8369/)で整理しています。 ### JWTを受け取る側の検証手順｜署名・有効期限・発行者クレームの確認 トークンの形式として広く使われるのが[JWT（RFC 7519）](https://www.rfc-editor.org/rfc/rfc7519.html)です。受け取る側は、署名の検証と、有効期限（`exp`）・発行者（`iss`）・宛先（`aud`）クレームの確認を省略できません。デコードしただけで中身を信用する実装は、改ざんされたトークンをそのまま受け入れてしまいます。署名アルゴリズムは受け入れる種類をこちらで固定し、トークン側のヘッダーに従わないようにしてください。構造と検証手順は[JWTとは？構造・署名検証の仕組みとセッション・OAuth/OIDCとの違いを実装視点で解説](https://www.issoh.co.jp/tech/details/13453/)で詳しく解説しています。 ## API連携のエラー処理とリトライ設計｜本番運用に耐える実装の要件 API連携の品質は、正常系ではなくエラー処理で決まります。相手はネットワークの向こうにある他人のシステムであり、遅延・停止・仕様変更は前提条件です。この章では応答コード別の処理、リトライ、レート制限対応を、コードで設計します。 ### 4xx・5xxエラーレスポンスの分類と実装で分けるべき復旧処理 エラー応答は「自分側の問題（4xx）」と「相手側の問題（5xx）」で処理を分けます。`400`や`422`はリクエスト内容の誤りなので、何度送り直しても結果は変わらず、リトライではなく修正とログ記録が正解です。`401`と`403`は認証・権限の問題で、トークン更新か設定見直しに回します。一方`500`や`503`は相手側の一時障害の可能性があり、リトライで回復が見込めます。 この分類を実装せず全エラーを一律リトライにすると、直らない400系を延々と再送して障害を増幅させかねません。分岐は次のように1か所へまとめておくと、呼び出し元ごとに判断がぶれません。 ``` def decide_action(status_code): """ステータスコードから次の動作を決める""" if status_code in (400, 404, 409, 422): return "stop" # 送り直しても直らない：ログに残して止める if status_code == 401: return "refresh" # トークンを更新して1回だけ再実行する if status_code == 403: return "stop" # 権限の設定を見直す（再送しない） if status_code == 429 or status_code >= 500: return "retry" # 待ってから再送する（冪等なリクエストに限る） return "ok" ``` エラー時に「どのエンドポイントに・何を送り・何が返ったか」をログに残すことも、切り分け時間を大きく左右します。提供元がエラー本文を[RFC 9457（Problem Details for HTTP APIs）](https://www.rfc-editor.org/rfc/rfc9457.html)の`application/problem+json`形式で返すなら、`type`と`detail`をそのままログに残すことが可能です。自社APIを公開する側としてエラー応答を設計する観点は[APIエラーレスポンス設計とは？コード体系・リトライ判断・漏洩防止の実装手順](https://www.issoh.co.jp/tech/details/17229/)で扱っています。 ### リトライ実装と冪等性の担保｜Idempotency-Keyで二重登録を防ぐ再送設計 リトライを入れる前に確認すべきは、そのリクエストが冪等（何度実行しても結果が同じ）かどうかです。[RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html)の定義ではGET・PUT・DELETEは冪等、POSTは冪等ではありません。つまり注文登録や決済のPOSTを無条件に再送すると、タイムアウトで「実は成功していた」ケースで二重決済・二重登録が起きます。 対策は、提供元が対応していれば一意の冪等キーを付けて再送を安全化すること、対応がなければ再送前に照会APIで結果を確認することです。`Idempotency-Key`ヘッダーはIETFでドラフトが出ていましたが失効しており、RFCにはなっていません（2026年9月時点）。仕様は提供元ごとに違うため、連携先のドキュメントを必ず確認します。代表例の[Stripeの冪等リクエスト仕様](https://docs.stripe.com/api/idempotent%5Frequests)では、キーはクライアントが生成し（V4 UUID推奨・最長255文字）、24時間以上経ったキーは削除されうると書かれています。 ``` import time import uuid import requests def create_order(session, payload, max_attempts=3): # キーは業務データと一緒に保存し、再送では必ず同じ値を使う key = str(uuid.uuid4()) for attempt in range(max_attempts): try: resp = session.post( "https://api.example.com/v1/orders", json=payload, headers={"Idempotency-Key": key}, timeout=(3.05, 10), ) except (requests.ConnectionError, requests.Timeout): time.sleep(2 ** attempt) # 1秒・2秒・4秒と待機を伸ばす continue # 同じキーで送り直す if resp.status_code == 429 or resp.status_code >= 500: time.sleep(2 ** attempt) continue resp.raise_for_status() return resp.json() raise RuntimeError("再送上限に達した：照会APIで登録結果を確かめる") ``` 再送間隔は固定にせず、指数バックオフ（1秒→2秒→4秒と間隔を広げる）にゆらぎを加えるのが定石です。多数のクライアントが同じタイミングで再送すると、復旧直後の相手に負荷が集中するためです。ジッターの入れ方やリトライ回数の予算の決め方は[リトライパターンとは？指数バックオフ・ジッター・リトライ予算の実装判断](https://www.issoh.co.jp/tech/details/16185/)で、キーの保存と応答の再生まで含めた受け手側の実装は[冪等キーとは？Idempotency-Keyの発行・保存・再生の実装](https://www.issoh.co.jp/tech/details/16293/)で扱っています。冪等性という考え方そのものと担保パターンは[冪等性とは？読み方・意味からAPI・IaCでの担保方法まで実装者向けに解説](https://www.issoh.co.jp/tech/details/13382/)で掘り下げています。 ### レート制限とタイムアウトへの対応｜429応答とRetry-Afterの実装 多くのAPIは単位時間あたりの呼び出し回数に上限を設けており、超過すると`429`（Too Many Requests）が返ります。[RFC 6585](https://www.rfc-editor.org/rfc/rfc6585.html)は429の応答にRetry-Afterヘッダーを付けてよいと定めており、付いていればその秒数だけ待ってから再開します。 Pythonなら、requestsが内部で使う[urllib3のRetry](https://urllib3.readthedocs.io/en/stable/reference/urllib3.util.html)（2026年9月時点で2.8系）に任せると、バックオフとRetry-Afterの処理を自前で書かずに済みます。公式リファレンスでは、既定で再送するメソッドはGET・PUT・DELETE・HEAD・OPTIONS・TRACEでPOSTを含まず、Retry-Afterを尊重する設定が既定で有効です。 ``` import requests from requests.adapters import HTTPAdapter from urllib3.util.retry import Retry retry = Retry( total=4, backoff_factor=1, # 1回目の再送は即時、以降は 2秒・4秒・8秒 と伸ばす backoff_jitter=0.5, # 待機に最大0.5秒のゆらぎを足す status_forcelist=[429, 500, 502, 503, 504], respect_retry_after_header=True, # 429・503のRetry-Afterに従う ) # allowed_methods は既定のまま：POSTは自動で再送しない session = requests.Session() session.mount("https://", HTTPAdapter(max_retries=retry)) resp = session.get("https://api.example.com/v1/orders", timeout=(3.05, 10)) ``` 設計段階でやるべきことは2つです。第一に、リファレンスの上限値と自システムの想定呼び出し数を突き合わせ、上限に収まらないならバッチ化やキャッシュで呼び出し自体を減らすこと。第二に、クライアント側のタイムアウトを明示的に設定することです。タイムアウト未設定のHTTPクライアントは相手の遅延に無限に付き合い、スレッドやコネクションを使い切って自システム側の障害に波及します。接続タイムアウトと読み取りタイムアウトを分けて、業務が許す範囲で短めに切るのが安全側の設計です。 ## Webhookで通知を受ける実装｜署名検証と重複配信への備え方 決済完了や在庫変動のように、相手側で起きたことをすぐ知りたい場合はWebhookで通知を受けます。受信用のURLは外部に公開されるため、誰でもリクエストを送れる前提で実装します。守るべきは、署名を検証して送信元を確かめること、同じイベントが2回以上届いても処理が1回で済むようにすること、の2点です。 署名の方式は提供元ごとに異なるものです。[GitHubの公式ドキュメント](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries)を例にとると、共有シークレットと受信した本文からHMAC-SHA256を計算し、`X-Hub-Signature-256`ヘッダーの値（`sha256=`で始まる）と比べます。比較には通常の等号ではなく、処理時間から値を推測されない定数時間の比較関数を使うよう求めています。 ``` import hashlib import hmac def verify_signature(raw_body, secret, signature_header): """受信した本文（bytes）と署名ヘッダーを照合する""" if not signature_header: return False digest = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest() expected = "sha256=" + digest # 定数時間で比較する（== は使わない） return hmac.compare_digest(expected, signature_header) ``` 署名はJSONに変換する前の生の本文で計算します。フレームワークが本文を先に解析して整形すると、1バイトでもずれれば検証を通すことはできません。重複配信への備えとしては、イベントIDを保存しておき、処理済みのIDなら何もせず200を返す作りにします。受信処理を重くすると相手側がタイムアウトとみなして再送してくるため、受け取ったらキューに積んで素早く応答するのが定石です。受信側の手順全体は[Webhookの実装方法と作り方｜手順と署名検証・リトライ・冪等性を解説](https://www.issoh.co.jp/tech/details/1378/)で詳しく扱っています。 ## API連携実装のテストと運用監視｜モック検証から障害検知まで 実装が済んだら、本番接続の前にテストで潰せる不具合を潰し、公開後は異常に気づける仕掛けを用意します。連携は自社だけで完結しないため、テストと監視の設計が単体機能より一段厚くなります。 ### テスト環境とモックサーバーによる動作確認｜本番接続前の検証項目 検証は2層で行います。提供元のサンドボックスがあれば、認証フロー・正常系・代表的なエラー系をそこで通すのが第一層です。サンドボックスで再現しにくい異常系（500応答・タイムアウト・不正なJSON）は、モックサーバーを立てて意図的に異常応答を返させて確認します。モックの方式選定と、実際のAPIとモックの仕様がずれていく問題への対策は[APIモッキングとは？モックサーバーの方式選定と契約ドリフト対策](https://www.issoh.co.jp/tech/details/16308/)で整理しています。 検証項目として最低限、次の4点を通します。 - 認証エラー（401）からトークン更新を経て復帰できるか - リトライ回数の上限で止まり、上限到達をログに残すか - 429とRetry-Afterに従って待機するか - 途中で失敗したときにデータが半分だけ登録された状態にならないか 正常系だけ確認して公開すると、初回の相手側障害でエラー処理の未実装が一斉に露呈します。 ### 公開後の監視とログ設計｜API連携の障害を切り分ける記録項目 公開後の監視は、成功率・応答時間・エラーコード別件数の3指標を継続して見るのが基本形です。閾値を決めてアラートにし、「5xxが5分間で一定件数を超えたら通知」のように機械に検知させます。ログには相手先エンドポイント・リクエストの要約・ステータスコード・所要時間・相関IDを残し、個人情報やAPIキーそのものは記録しない設計にします。 障害時の切り分けは「自社側か相手側か」の判定が最初の分岐であり、この記録があれば数分で判断可能です。相手のAPI仕様変更や廃止の告知を追う運用担当を決めておくことも、地味ですが長期運用では効きます。複数のAPI連携を束ねて認証やレート制限を一元化したくなったら、[APIゲートウェイ](https://www.issoh.co.jp/tech/details/13210/)を入口に置く構成も検討対象になります。 ## 自前実装とiPaaS・受託開発の使い分け｜規模と要件による判断基準 最後に、API連携を自前でプログラミングするか、連携ツール（iPaaS）で済ませるか、外部に開発を任せるかの判断を整理します。ここは条件で言い切ります。 | 条件 | 向く進め方 | 理由 | | ------------- | -------------- | ------------ | | SaaS同士の定型連携 | iPaaS | 早く組めて保守も軽い | | 一部だけ独自処理がある | iPaaS＋小さな自作API | 例外部分だけ書けば済む | | 決済・在庫・会計を扱う | 自前実装 | 整合性と再送の制御が要る | | 基幹と複数サービスをまたぐ | 受託開発 | 設計から一貫して組む | ### 自前実装を選ぶ条件と見送る場面｜開発工数と保守体制で決める判断基準 自前実装を選ぶのは、連携に業務ロジックが絡む場合（変換・突合・承認フローを挟む等）、扱うデータの整合性要件が高い場合（決済・在庫・会計）、呼び出し量が多く実行単価を抑えたい場合です。逆に見送るべきなのは、SaaS同士の定型的なデータ受け渡しだけが目的で、社内に保守できるエンジニアがいない場合です。この条件ではZapierやMakeのようなiPaaSで組む方が早く、障害対応も追いやすくなります。 中間の「一部だけロジックが要る」ケースは、iPaaSで全体を組んで例外部分だけ小さな自作APIを挟む構成が現実解です。判断を誤りやすいのは保守の見積もりで、API連携は作って終わりではなく、相手の仕様変更のたびに追従工数が発生します。実装者が1人しかいない連携は、その人の異動と同時に負債へ変わるのが実情です。この記事のコード例を読んで「自社で書いて保守し続けられるか」を一度見積もってみると、判断の材料になります。 ### 外部パートナーへの依頼が向くケース｜要件定義から任せる進め方 基幹システムや複数サービスをまたぐ連携基盤のように、方式選定・認証設計・エラー処理・監視までを一貫して設計する必要がある案件は、API連携の実装経験を持つ開発会社に要件定義から入ってもらう方が総コストは下がります。依頼時は「どのシステムとどのシステムを、どのデータについて、どの頻度でつなぐか」を一覧にして渡すのが、精度の高い見積もりへの近道です。 一創では[API開発・システム連携](https://www.issoh.co.jp/service/system/api/)として、外部APIとの接続実装から自社APIの設計・公開までを受託しています。既存システムの仕様が不明瞭な状態からの調査込みの相談にも対応しているため、リファレンスが存在しない社内システム同士の連携で行き詰まっている場合の出口になります。 ## よくある質問 API連携の実装方法について、検索で多い質問に答えます。 ### API連携の実装には何から着手すればよいですか？ APIリファレンスの通読が最初の一歩です。エンドポイント・認証方式・レート制限・エラーコード表を確認し、実現したい業務フローが仕様上成立するかを先に判定します。成立が確認できたら開発者登録とAPIキー発行を済ませ、サンドボックスに対してcurlで1回呼んで疎通を確かめます。コードを書き始めるのはその後です。この順番なら手戻りが最小で済みます。 ### プログラミングの知識がなくてもAPI連携は実装できますか？ SaaS同士の定型的なデータ連携であれば、ZapierやMakeのようなiPaaSを使ってノーコードで構築できます。ただし対応コネクタがないAPIへの接続、複雑な変換ロジック、高い信頼性が要る決済・在庫系の連携はノーコードの守備範囲を超えます。その場合はプログラミングによる個別実装か、開発会社への依頼を検討してください。 ### API連携の実装にはどれくらいの期間がかかりますか？ 規模によって幅がありますが、公開APIへの単純な参照連携なら仕様確認込みで数日〜2週間程度、認証フローやエラー処理・リトライを備えた業務連携で1〜2か月程度が目安です。提供元の開発者登録に審査がある場合は、その待ち時間（数日〜数週間）が別途乗ります。期間を左右するのはコーディングよりも、相手仕様の調査とテスト環境の整備です。 ### Web API連携でよく発生するエラーには何がありますか？ 頻出は401（認証エラー・トークン期限切れ）、403（権限不足）、429（レート制限超過）、500・503（相手側障害）、そしてタイムアウトです。401はトークン更新処理の漏れ、429は呼び出し頻度設計の見積もり不足が典型原因として挙げられます。エラーコードごとに「再送してよいか」が異なるため、一律リトライにせず4xxと5xxで処理を分け、POSTの再送には冪等キーを付けるのが原則です。 ### APIキーはどのように管理すべきですか？ ソースコードへの直書きを避け、環境変数か秘密情報管理サービスに保管します。ブラウザやアプリなどクライアント側には埋め込まず、自社サーバーを経由して呼び出す構成にしてください。加えて、キーの権限は必要な操作だけに絞り、担当者の異動時や漏えいの疑いがある時に即時ローテーションできる手順を用意しておくと、事故時の被害を局所化できます。ユーザーの代理でデータを読む連携なら、固定のAPIキーではなくOAuth 2.0のトークンに切り替えることも検討します。 ## 関連記事 - [システム開発とは？種類・工程・依頼方法までの全体像をわかりやすく解説](https://www.issoh.co.jp/column/details/12847/)：API連携を含むシステム開発全体の工程と外注の進め方を整理しています。 - [RESTとは？REST APIの仕組みと6原則・SOAP/GraphQLとの違いを実装目線で解説](https://www.issoh.co.jp/tech/details/13588/)：本記事で第一候補としたREST方式の設計原則を掘り下げています。 - [JWTとは？構造・署名検証の仕組みとセッション・OAuth/OIDCとの違いを実装視点で解説](https://www.issoh.co.jp/tech/details/13453/)：トークン認証の実装で必須になる署名検証の手順を解説しています。 - [APIゲートウェイとは？役割・機能とリバースプロキシ／サービスメッシュとの違い・導入判断を解説](https://www.issoh.co.jp/tech/details/13210/)：複数API連携の入口を束ねる構成を検討する際の判断材料になります。 - [APIセキュリティとは？OWASP API Top 10の主要リスクと実装対策を解説](https://www.issoh.co.jp/tech/details/13793/)：認証情報の保護を含むAPI固有の攻撃と対策を体系的にまとめています。 - [Webhookの実装方法と作り方｜手順と署名検証・リトライ・冪等性を解説](https://www.issoh.co.jp/tech/details/1378/)：通知を受ける側の実装を、本記事より一段詳しく扱っています。 - [リトライパターンとは？指数バックオフ・ジッター・リトライ予算の実装判断を解説](https://www.issoh.co.jp/tech/details/16185/)：再送の間隔と回数の決め方を掘り下げています。 --- 出典: [API連携の実装方法：REST・認証・エラー処理の手順をcurlとPythonのコード例で解説]()（株式会社一創）