TERM GL-0007

API

読みえーぴーあい ENApplication Programming Interface

別名エーピーアイ / アプリケーションプログラミングインターフェース

プログラミング自動化 AI UPDATED 2026-11-04

DEFINITION

APIとは、ソフトウェア同士が機能やデータをやり取りするための約束や手順を定めたインターフェースです。

API は、ソフトウェアどうしが機能やデータをやり取りするための約束事です。人間が画面を見て操作する代わりに、別のプログラムが決められた手順で呼び出せるようにします。Web サービス、業務システム、装置制御、機械設計データの受け渡しまで、実務では非常に広い範囲で使われます。

何を「約束」しているのか

API では、相手に公開する機能の名前、入力の形、返ってくる値、失敗したときの扱いなどを決めます。たとえば「この住所を渡すと天気情報が返る」「この ID を渡すと部品情報が返る」といった取り決めです。

重要なのは、内部の実装を直接触らなくてもよい点です。API の利用者は、内部が Python で書かれているか、別の言語で書かれているかを必ずしも知る必要はありません。利用側は、決められた入出力さえ守れば機能を使えます。

呼び出し方と返し方の型

API の多くは、リクエストとレスポンスという 2 つの流れで考えると理解しやすいです。利用側が要求を送り、サービス側が結果を返します。Web API では HTTP を使うことが多く、URL、メソッド、ヘッダ、本文などで情報を渡します。

返却データの形式としては JSON がよく使われます。JSON はキーと値を組にした軽量なデータ表現で、プログラムで扱いやすいのが利点です。たとえば部品名、寸法、材質、更新日時などを構造化して返せます。

JSON で返るイメージ

{
  "part_name": "bracket",
  "width_mm": 42.5,
  "material": "PETG"
}

API は「何を返すか」だけでなく、「どこまでを成功とみなすか」も含めて設計されます。たとえば見つからない、権限がない、入力が不正、サーバ側で処理できない、などを区別して返すことが重要です。

使い分ける API の種類

API と一口にいっても、相手や用途によって呼び方が変わります。外部の開発者向けに公開する公開 API、同じ組織の内部だけで使う内部 API、別のプログラムから呼ぶライブラリ API などがあります。

公開 API: 第三者向け。認証、利用制限、互換性維持が重要
内部 API: 社内システム間で使う。変更しやすいが、境界設計が重要
ライブラリ API: 関数やクラスとして提供される。コードから直接呼ぶ
Web API: HTTP 経由で呼ぶ。現在もっとも目にする機会が多い

機械設計や自動化の現場では、CAD データや装置データ、クラウドサービスの情報を連携するために API が使われます。たとえば DXF を扱うサービス、在庫管理、ログ収集、認証基盤などをつなぐときに有効です。

呼び出し例とエラーの見方

実務では、API を「呼べるか」より「安定して使えるか」が大切です。成功時だけでなく、失敗時の応答を確認しておくと、運用でのトラブルを減らせます。

import requests

url = "https://example.com/api/parts/123"
response = requests.get(url, timeout=5)

print(response.status_code)
print(response.json())

この例では、`status_code` で HTTP の結果を見て、`json()` で返却データを辞書として受け取ります。200 番台は成功、400 番台は利用側の問題、500 番台はサーバ側の問題という読み方が基本です。

認証と権限の境界

API には、誰でも使えるものは少なく、たいてい認証と権限管理があります。認証は「誰かを確かめること」、権限は「何をしてよいかを決めること」です。OAuth 2.0 や IAM、サービスアカウント、サービスアカウントキーは、この境界を扱うときによく出てきます。

API キーだけで済む場合もありますが、より厳密な制御が必要な場面ではトークンや署名付きの認証方式を使います。特に外部公開や自動化では、鍵の漏えい対策、権限の最小化、有効期限の設定が重要です。

設計でつまずきやすい点

API は「作れば終わり」ではなく、互換性を保ちながら育てる必要があります。変更の影響が大きいので、設計段階で次の点を意識すると扱いやすくなります。

パラメータ名や型をむやみに変えない
返却形式を急に変えない
エラー応答を文面だけでなくコードでも分ける
バージョンを分けて古い利用者を守る
レート制限やタイムアウトを考える

特に自動化では、呼び出し先の一時停止や遅延がそのまま処理停止につながります。n8n のようなワークフロー自動化ツールでも、API の応答形式が変わると連携全体が崩れやすくなります。

似た言葉との境目

API は、単なる通信路ではなく「使い方の取り決め」まで含む点が特徴です。似た言葉と混同すると、設計や運用で誤解しやすくなります。

用語	意味	API との違い
インターフェース	境界や接点の総称	API はその中でも機能の公開方法を指すことが多い
ライブラリ	再利用可能なコードの集まり	ライブラリは実体、API は使い方の約束
プロトコル	通信手順の規格	API はプロトコルを使って設計されることがある
JSON	データ表現形式	API の返却形式として使われることが多い
LLM API	大規模言語モデルを呼ぶ口	API の一種で、推論結果や生成結果を受け取る