愛（AI）と共に：✍️APIを実際に作り、使用する⛏️🧠AIの組み込みで活用はしてたけど😅

watabin｜愛（AI）と共に

2026年7月7日 11:15

まずはAPIの基本的な考え方からおさらいします。

その後は、APIを実際に作って、利用してみます。
色々とイメージが湧き易いようにサーバー側になるAPIプログラムは3種類くらい書いてみます。
クライアントはHTMLで記述するのが分かり易そうです。

そんな流れで話を進めていこうと思います。
意外と「仕様書」が重要そうです。

🟢APIとは？

**API（Application Programming Interface）**とは、

「あるプログラムの機能を、他のプログラムから決められたルールで利用するための窓口」

のことです。

人間で例えると、APIはレストランの店員のような存在です。

あなた（利用するプログラム）が注文する
店員（API）が厨房へ伝える
厨房（サーバーや別のプログラム）が料理を作る
店員（API）が料理を持ってくる

あなたは厨房の作り方を知る必要はなく、「メニュー（APIの仕様）」だけ知っていれば注文できます。

APIが必要な理由

例えば天気アプリを作るとします。

天気データを自分で観測するのは大変なので、

天気アプリ
      │
      │ API
      ▼
気象サービス

という形で、気象サービスが提供するAPIからデータを受け取ります。

これにより、

データを自分で管理しなくていい
常に最新情報を取得できる
開発がとても楽になる

というメリットがあります。

APIは「約束事」

APIには「こういう形式で送ってください」というルールがあります。

例えば

GET /weather?city=Tokyo

というリクエストを送ると、

{
  "city": "Tokyo",
  "temperature": 31,
  "weather": "Sunny"
}

というデータが返ってきます。

つまり

どこに送るか（URL）
何を送るか
どんな形式で返ってくるか

が決められています。

APIはPC同士の会話

実際には次のような流れになります。

PC①（クライアント）

「東京の天気を教えて」

        │
        │ HTTP通信
        ▼

PC②（サーバー）

「東京は31℃、晴れです」

        ▲
        │
        │ JSONデータ
        │

PC①

この「問い合わせ」と「返事」の仕組みがAPIです。

APIは同じPC内でも使われる

APIというとインターネットを思い浮かべがちですが、同じPC内でも使われます。

例えば

Excel
   │
   │ API
   ▼
Windows

Excelが

ファイルを開く
印刷する
ウィンドウを表示する

といった操作をするときは、Windowsが提供するAPIを利用しています。

つまりAPIは、

PCとPC
プログラムとプログラム
アプリとOS

など、さまざまな場面で使われています。

APIを一言でまとめると

APIとは、

「プログラム同士が決められたルールに従って機能やデータをやり取りするための窓口」

です。

重要なのは、「内部の仕組みを知らなくても、使い方（ルール）さえ守れば利用できる」という点です。

次は、実際に2台のPCがHTTP APIを使ってどのようなメッセージを送受信するのかを、リクエスト・レスポンスの具体例（HTTPメッセージやJSONを含む）で順を追って見ていきましょう。そうすると、API通信のイメージがかなり具体的になります。

🔴「お天気API」を作ってみる

実際のAPI開発では、次の流れになることが多いです。

① APIの仕様を決める
        ↓
② サーバー(API)を作る
        ↓
③ クライアント(Webやアプリ)を作る
        ↓
④ 動作確認・改善

今回は学習用なので、固定のデータを返すAPIにすると仕組みだけに集中できます。

今回作るもの

             HTTP

┌────────────────────┐
│ クライアント        │
│ HTML(JavaScript)   │
└────────┬───────────┘
         │ GET /weather
         ▼
┌────────────────────┐
│ APIサーバー        │
│ Python / Go / Java │
└────────┬───────────┘
         │
         ▼
JSONを返す

返すデータは共通です。

{
    "weather": "晴れ",
    "temperature": 30,
    "humidity": 65,
    "datetime": "2026-07-07 10:30:00"
}

サーバーだけ言語を変えます。

Python → 晴れ
Go → 曇り
Java → 雨

こうすると「APIは言語が違っても使い方は同じ」がよく分かります。

① API仕様

まず仕様を決めます。

URL

GET /weather

レスポンス(JSON)

{
    "weather": "晴れ",
    "temperature": 30,
    "humidity": 65,
    "datetime": "2026-07-07 10:30:00"
}

これがAPIの約束になります。
ちなみに「仕様書」風にまとめると下記のようになります。
項目：内容
URL：/weather
メソッド：GET
レスポンス形式：JSON
weather：天気（文字列）
temperature：気温（整数）
humidity：湿度（整数）
datetime：サーバーの現在日時（文字列）

② Python(APIサーバー)

Flaskを使います。

from flask import Flask, jsonify

app = Flask(__name__)

@app.route("/weather")
def weather():
    return jsonify({
        "weather": "晴れ",
        "temperature": 30,
        "humidity": 65,
        "datetime": "2026-07-07 10:30:00"
    })

app.run(debug=True)

アクセスすると

http://localhost:5000/weather

↓

{
    "weather":"晴れ",
    "temperature":30,
    "humidity":65,
    "datetime":"2026-07-07 10:30:00"
}

③ Go(APIサーバー)

package main

import (
    "encoding/json"
    "net/http"
)

type Weather struct {
    Weather    string `json:"weather"`
    Temperature int   `json:"temperature"`
    Humidity    int   `json:"humidity"`
    Datetime    string `json:"datetime"`
}

func weatherHandler(w http.ResponseWriter, r *http.Request) {
    data := Weather{
        Weather: "曇り",
        Temperature: 27,
        Humidity: 72,
        Datetime: "2026-07-07 10:30:00",
    }

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(data)
}

func main() {
    http.HandleFunc("/weather", weatherHandler)
    http.ListenAndServe(":8080", nil)
}

④ Java(APIサーバー)

例えばSpring Bootなら

@RestController
public class WeatherController {

    @GetMapping("/weather")
    public Map<String, Object> weather() {

        Map<String, Object> map = new HashMap<>();

        map.put("weather", "雨");
        map.put("temperature", 24);
        map.put("humidity", 88);
        map.put("datetime", "2026-07-07 10:30:00");

        return map;
    }
}

⑤ クライアント(HTML)

個人的な趣味もありますが、教育や学用には”HTML”がおすすめです。

理由としては

APIだけに集中できる
Pythonなどの言語で書く必要がない（むしろ二度手間）
JavaScriptのfetch()がAPIそのものだから

index.html

<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8">
<title>天気情報</title>
</head>

<body>

<h1>天気情報</h1>

<p>天気：<span id="weather"></span></p>
<p>気温：<span id="temp"></span>℃</p>
<p>湿度：<span id="hum"></span>%</p>
<p>日時：<span id="dt"></span></p>

<script>
fetch("http://localhost:5000/weather")
    .then(response => response.json())
    .then(data => {

        document.getElementById("weather").textContent = data.weather;
        document.getElementById("temp").textContent = data.temperature;
        document.getElementById("hum").textContent = data.humidity;
        document.getElementById("dt").textContent = data.datetime;

    });
</script>

</body>
</html>

ブラウザはサーバーに

GET /weather

を送り、

PythonサーバーからJSONを受け取り、

画面へ表示します。

通信の流れ

HTML(JavaScript)

fetch("/weather")

        │
        │ HTTP GET
        ▼

Python Flask

{
 weather:"晴れ",
 temperature:30,
 humidity:65,
 datetime:"..."
}

        │
        │ JSON
        ▼

HTML

画面へ表示

GoでもJavaでも全く同じです。
クライアント（HTML）のポート番号だけ書き換えてください。

🔵この教材をさらに面白くするアイデア

先に紹介した3、3つのAPIサーバーを同時に動かし、クライアントから切り替えて呼び出す構成も考えてみました。

Python(API)  localhost:5000
       │
Go(API)      localhost:8080
       │
Java(API)    localhost:8081
       │
       ▼
HTML

「Python」ボタン
「Go」ボタン
「Java」ボタン

ボタンを押すたびに、それぞれのAPIから天気情報を取得して表示します。

この構成だと、

APIの仕様（JSON）が同じなら、実装言語が違ってもクライアントはほとんど変更不要
サーバーとクライアントが独立して開発できる
「APIは契約（仕様）が重要」という考え方

を実際に体験できます。

あと、せっかくなので、一部は固定値ではなく「現在時刻だけはサーバーで毎回生成する」といった機能を少し追加してみます。
この流れだと、実務で使われるAPIの設計に自然につながり、学べる内容が一気に増えます。

APIの設計（JSON形式を統一）
サーバー側の処理（日時を毎回生成）
クライアント側の処理（APIを切り替えて呼び出す）
HTTP通信
JSON
異なる言語でも同じAPIなら同じクライアントで利用できる

全体構成は次のようになります。

                  ブラウザ

        ┌─────────────────────┐
        │ 天気表示            │
        │                     │
        │ [Python] [Go] [Java]│
        │                     │
        │ 天気：              │
        │ 気温：              │
        │ 湿度：              │
        │ 日時：              │
        └─────────┬───────────┘
                  │
      ┌───────────┼────────────┐
      │           │            │
      ▼           ▼            ▼
localhost:5000 localhost:8080 localhost:8081
 Python API      Go API        Java API
   晴れ           曇り            雨

① Python (Flask)

from flask import Flask, jsonify
from datetime import datetime

app = Flask(__name__)

@app.route("/weather")
def weather():

    return jsonify({
        "weather": "晴れ",
        "temperature": 30,
        "humidity": 65,
        "datetime": datetime.now().strftime("%Y-%m-%d %H:%M:%S")
    })

app.run(port=5000, debug=True)

② Go

package main

import (
	"encoding/json"
	"net/http"
	"time"
)

type Weather struct {
	Weather     string `json:"weather"`
	Temperature int    `json:"temperature"`
	Humidity    int    `json:"humidity"`
	Datetime    string `json:"datetime"`
}

func weatherHandler(w http.ResponseWriter, r *http.Request) {

	data := Weather{
		Weather:     "曇り",
		Temperature: 27,
		Humidity:    72,
		Datetime:    time.Now().Format("2006-01-02 15:04:05"),
	}

	w.Header().Set("Content-Type", "application/json")
	json.NewEncoder(w).Encode(data)

}

func main() {

	http.HandleFunc("/weather", weatherHandler)

	http.ListenAndServe(":8080", nil)

}

③ Java (Spring Boot)

@RestController
public class WeatherController {

    @GetMapping("/weather")
    public Map<String,Object> weather(){

        Map<String,Object> map = new HashMap<>();

        map.put("weather","雨");
        map.put("temperature",24);
        map.put("humidity",88);
        map.put("datetime",
                LocalDateTime.now()
                             .format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")));

        return map;
    }

}

※Spring Bootのデフォルトポートは8080なので、

application.properties

へ

server.port=8081

を追加します。

④ クライアント(index.html)

<!DOCTYPE html>
<html lang="ja">

<head>
<meta charset="UTF-8">
<title>天気APIデモ</title>

<style>

body{
    font-family: sans-serif;
    margin:30px;
}

button{
    width:120px;
    height:40px;
    margin:5px;
    font-size:16px;
}

table{
    margin-top:20px;
    border-collapse:collapse;
}

td{
    border:1px solid black;
    padding:8px;
}

</style>

</head>

<body>

<h2>天気APIデモ</h2>

<button onclick="loadWeather('http://localhost:5000/weather')">
Python
</button>

<button onclick="loadWeather('http://localhost:8080/weather')">
Go
</button>

<button onclick="loadWeather('http://localhost:8081/weather')">
Java
</button>

<table>

<tr>
<td>天気</td>
<td id="weather"></td>
</tr>

<tr>
<td>気温</td>
<td id="temp"></td>
</tr>

<tr>
<td>湿度</td>
<td id="hum"></td>
</tr>

<tr>
<td>日時</td>
<td id="dt"></td>
</tr>

</table>

<script>

function loadWeather(url){

fetch(url)
.then(res=>res.json())
.then(data=>{

document.getElementById("weather").textContent=data.weather;
document.getElementById("temp").textContent=data.temperature+" ℃";
document.getElementById("hum").textContent=data.humidity+" %";
document.getElementById("dt").textContent=data.datetime;

})
.catch(err=>alert(err));

}

</script>

</body>
</html>

動作イメージ

① Pythonボタン

GET http://localhost:5000/weather

↓

{
  "weather":"晴れ",
  "temperature":30,
  "humidity":65,
  "datetime":"2026-07-07 14:32:18"
}

② Goボタン

GET http://localhost:8080/weather

↓

{
  "weather":"曇り",
  "temperature":27,
  "humidity":72,
  "datetime":"2026-07-07 14:32:21"
}

③ Javaボタン

GET http://localhost:8081/weather

↓

{
  "weather":"雨",
  "temperature":24,
  "humidity":88,
  "datetime":"2026-07-07 14:32:25"
}

この教材のポイント

この構成の一番の学びは、「クライアントはサーバーの実装言語を意識しない」ということです。

クライアントが違いとして知っているのはアクセス先のURLだけです。

Python → http://localhost:5000/weather
Go     → http://localhost:8080/weather
Java   → http://localhost:8081/weather

返ってくるJSONの形式が同じなので、loadWeather() 関数はどのAPIに対しても同じコードで動作します。

これは実際のWebシステムでも非常によく使われる設計で、「APIの仕様（契約）を守れば、サーバー側の実装は自由に変更できる」という考え方を体験できる、教育用として非常に分かりやすいサンプルになるでしょう。

この題材は、APIの本質を伝えるのにとても良い構成だと個人的には思いました。

実際の開発でも、プログラムを書く前にAPI仕様を決めることが非常に重要です。

例えば、今回の話を教材にするなら、最初に次のような「仕様書」を見せるのも効果的です。
「APIは約束事」という考え方が伝えやすくなると思います。

項目：内容
URL：/weather
メソッド：GET
レスポンス形式：JSON
weather：天気（文字列）
temperature：気温（整数）
humidity：湿度（整数）
datetime：サーバーの現在日時（文字列）

そして、「この仕様を守ること」が大事だと説明します。

Pythonで作っても
Goで作っても
Javaで作っても

同じ仕様のJSONを返すようにすれば、クライアントは変更せずに利用できます。

逆に、例えばGoだけ次のように項目名を変えてしまうと、

{
  "weather": "曇り",
  "temp": 27,
  "humidity": 72,
  "datetime": "2026-07-07 15:00:00"
}

クライアントは temperature を探しているため、気温が表示されなくなります。

「プログラムは動いているのに画面がおかしい」という現象になり、API仕様を守ることの重要性を実感できます。

今回の話を教材にするなら、次のような流れがおすすめです。

APIとは何か（レストランの例）
API仕様を決める（URL・JSON・HTTPメソッド）
PythonでAPIを作る
GoでAPIを作る
JavaでAPIを作る
1つのHTMLクライアントから3つのAPIを切り替えて利用する
あえて仕様を壊してみる（例：temperature を temp に変更）
「なぜ動かなくなったのか？」を考える
API仕様を元に戻して正常に動作することを確認する

最後の「わざと壊して原因を考える」という演習は、受講者の印象に強く残ります。「APIは単なる通信ではなく、仕様という契約を守ることで初めて連携できる」ということを体験的に理解できるからです。

この教材なら、APIの基礎から実務で大切な「設計」「契約」「疎結合」の考え方まで、自然な流れで学んでもらえると思います。