APIの正体はJSONを返すHTTP — Node.jsで作る

Node.jsでAPIを作る。APIサーバーと波括弧のデータカード、送受信する端末。

APIは特別な仕組みではなく、JSONを返すHTTPです。GETとPOSTを実装して、その正体を確かめます。

前回: サーバーとは待ち続けるプログラム — 手で書いて確かめる 作業場所はVMの中(Ubuntu)です。前回作った ~/server/server.js を、そのまま育てます。

前回、サーバーはポートを掴んで待ち続けるプログラムだと確かめました。

次に出てくる言葉が API です。そして、この単語もイメージが先行しています。

何か高度な仕組み。企業が公開している特別なもの。

違います。 前回すでに、あなたはAPIを1つ作っています。/time がそれです。

{"now":"2026-09-02T05:20:11.482Z"}

JSONを返しただけでした。それがAPIです。

対象レベル: 初級〜中級 / 区分: 必修

目次

この記事でわかること

  • APIは「JSONを返すHTTP」でしかないということ
  • req.body は勝手に入っていない。 本文は自分で組み立てる必要があること
  • 第3段階で「フロントでは直せない」と書いた CORS を、サーバー側から解除する方法
  • Express が肩代わりしているのが何なのか(そして、それが分かってから使うべき理由)

この記事でやること

  1. 前回の server.js に、GET でデータを返すAPIを足す
  2. POST を受け取る(本文を自分で組み立てる)
  3. ブラウザから fetch して、CORSを自分で解除する
  4. Express で同じものを書き直し、行数と手間を比べる

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
API画面ではなくデータ(多くはJSON)を返すための入り口。人間ではなく、別のプログラムが読む前提の返事です。
POSTリクエストの種類の1つで、本文を付けて送るもの。GETが「ください」なら、POSTは「これを登録してください」です。
ExpressNode.js でサーバーを書くときによく使うライブラリ。パスごとの分岐や本文の組み立てを代わりにやってくれます。
プリフライト(OPTIONS)ブラウザが本番のリクエストを送る前に「この送り方でいいですか」と先に確認しに行くこと。許可が返らないと本番は送られません。
jqターミナルでJSONを整形したり、条件で絞り込んだりする道具。1行で返ってくるJSONを読める形にします。

準備

サービスを止めて、手で動かす

前回 systemd に登録した人は、そのままだと編集しても反映されません。

bash
$ systemctl is-active myserver

active と返ったら、開発のあいだは止めます。

bash
$ sudo systemctl stop myserver

開発中は systemd を使いません。 直したら止めて立て直す、を何十回も繰り返すので、手で動かすほうが速いからです。 常駐させるのは「完成したものを動かし続けたいとき」です。役割が違います。記事の最後にまた登録します。

ポートを開ける

前回の後片づけで閉じた人は、開け直します。

bash
$ sudo ufw allow 3000/tcp
$ sudo ufw status

3000/tcp の行が出れば準備完了です。

① GET でデータを返す

~/server/server.js を、まるごと置き換えます。

bash
$ cd ~/server
$ nano server.js
const http = require("node:http");

// データはとりあえずメモリに置く(プログラムを止めると消えます)
let tasks = [
  { id: 1, title: "Linuxのコマンドを覚える", done: true },
  { id: 2, title: "サーバーを立てる", done: true },
  { id: 3, title: "APIを作る", done: false },
];

const server = http.createServer((req, res) => {
  console.log(`${req.method} ${req.url}`);

  if (req.method === "GET" && req.url === "/api/tasks") {
    res.writeHead(200, { "Content-Type": "application/json; charset=UTF-8" });
    res.end(JSON.stringify(tasks));
    return;
  }

  res.writeHead(404, { "Content-Type": "application/json; charset=UTF-8" });
  res.end(JSON.stringify({ error: "not found" }));
});

server.listen(3000, "0.0.0.0", () => {
  console.log("http://0.0.0.0:3000/ で待っています");
});

動かして、叩きます。

bash
$ node server.js

別のターミナルで:

bash
$ curl -s http://localhost:3000/api/tasks
[{"id":1,"title":"Linuxのコマンドを覚える","done":true},{"id":2,"title":"サーバーを立てる","done":true},{"id":3,"title":"APIを作る","done":false}]

これがAPIです。 ここまでで特別なものは何も使っていません。

読みやすく整える

1行で返ってくると読めません。 jq を入れると整形できます。

bash
$ which jq || sudo apt install -y jq
$ curl -s http://localhost:3000/api/tasks | jq
[
  {
    "id": 1,
    "title": "Linuxのコマンドを覚える",
    "done": true
  },
  ...
]

jq は「JSON用の grep」のような道具です。取り出すこともできます。

curl -s http://localhost:3000/api/tasks | jq '.[] | select(.done == false)'

まだ終わっていないものだけが出ます。この先ずっと使うので、入れておいて損はありません。

なぜ Content-Type を書くのか

application/json と名乗らないと、受け取った側は「ただの文字列」として扱います。

わざと text/plain に変えて、ブラウザで http://192.168.226.50:3000/api/tasks を開いてみてください(IPは自分の値に)。

Content-Typeブラウザの見え方
text/plainベタ書きの文字列がそのまま出る
application/json整形されて、折りたためる(Chrome / Firefox)

中身は1バイトも変わっていません。 変わったのは「これは何か」という名乗りだけです。

DNSとHTTPの回で curl.exe -I を使ってヘッダーを見ました。 あのとき見ていたのは、こういう名乗りです。今度は自分が名乗る側になりました。

[スクリーンショット: 01_api_json.png] ホストのブラウザで http://<VMのIP>:3000/api/tasks を開き、JSONが整形されて表示されている画面を撮ってください。

② POST を受け取る — 本文は勝手に来ない

ここが、生のNodeで一番驚くところです。

req.body   // ← undefined

本文は入っていません。 非同期処理の回でやった話が、ここで効いてきます。

HTTPの本文は、一度に全部届くとは限りません。

大きなデータは分割して届きます。だからNodeは「届いたぶんから順に渡すので、自分でつなげてください」という形にしています。受け取り終わるのを待つ必要がある — つまり非同期です。

server.js に足します。GETの分岐の下に入れてください。

  if (req.method === "POST" && req.url === "/api/tasks") {
    let body = "";

    req.on("data", (chunk) => {
      body += chunk;           // 届いたぶんをつなげる
    });

    req.on("end", () => {      // 全部届いたら、ここが呼ばれる
      let data;
      try {
        data = JSON.parse(body);
      } catch {
        res.writeHead(400, { "Content-Type": "application/json; charset=UTF-8" });
        res.end(JSON.stringify({ error: "JSONとして読めません" }));
        return;
      }

      if (!data.title) {
        res.writeHead(400, { "Content-Type": "application/json; charset=UTF-8" });
        res.end(JSON.stringify({ error: "title は必須です" }));
        return;
      }

      const task = { id: tasks.length + 1, title: data.title, done: false };
      tasks.push(task);

      res.writeHead(201, { "Content-Type": "application/json; charset=UTF-8" });
      res.end(JSON.stringify(task));
    });
    return;
  }

立て直して、送ります。

bash
$ curl -s -X POST http://localhost:3000/api/tasks \
    -H "Content-Type: application/json" \
    -d '{"title":"データベースを繋ぐ"}' | jq
{
  "id": 4,
  "title": "データベースを繋ぐ",
  "done": false
}

もう一度 GET すると、4件になっています。

curl のオプション意味
-X POSTメソッドを指定(既定はGET)
-H "Content-Type: ..."ヘッダーを付ける(「JSONを送ります」と名乗る)
-d '{...}'本文

壊してみる

エラーの側も確かめてください。 動くほうだけ試して終わりにすると、失敗したときに何が返るか分からないままになります。

bash
$ curl -i -s -X POST http://localhost:3000/api/tasks \
    -H "Content-Type: application/json" -d 'こわれたJSON'
HTTP/1.1 400 Bad Request
...
{"error":"JSONとして読めません"}
bash
$ curl -i -s -X POST http://localhost:3000/api/tasks \
    -H "Content-Type: application/json" -d '{}'
HTTP/1.1 400 Bad Request
...
{"error":"title は必須です"}

try / catch を書かないと、サーバーごと落ちます。 JSON.parse は読めない文字列で例外を投げます。受け止めないとプロセスが終了し、以降のリクエストが全部繋がらなくなります。 「利用者が送ってくる値は、必ず壊れていると思って書く」が原則です。誰かが curl で適当な文字列を送るだけで落ちるサーバーを、外に出すわけにはいきません。

番号意味いつ返すか
200OK取得できた
201Created作成できた(POSTの成功はこちら)
400Bad Request送られてきた内容がおかしい(利用者側の問題)
404Not Foundそのパスは無い
500Internal Server Errorこちら側で例外が起きた

400番台は「あなたの送ったものがおかしい」、500番台は「こちらが壊れている」です。この区別を間違えると、自分のバグを利用者のせいにするAPIになります。

③ ブラウザから叩く — CORSを自分で解除する

ここが、この記事の山場です。

非同期処理の回で、こう書きました。

CORSエラーは、ブラウザが止めています。サーバーは正常に応答しています。 だから、この問題はフロントエンド側では直せません。 直すのはサーバー側です。 ここは第5段階でバックエンドを書くときにやります。

その第5段階です。今度は、直す側に回ります。

まず、止められることを確かめる

もう1つターミナルを開いて、第2段階から使っている ~/web/ を8000番で配ります。

bash
$ sudo ufw allow 8000/tcp
$ cd ~/web
$ python3 -m http.server 8000 --bind 0.0.0.0

ホストのブラウザで http://192.168.226.50:8000/ を開き、F12 → Console でこう打ちます。

fetch("http://192.168.226.50:3000/api/tasks")
  .then((r) => r.json())
  .then(console.log)
  .catch((e) => console.error("失敗:", e));
Access to fetch at 'http://192.168.226.50:3000/api/tasks' from origin
'http://192.168.226.50:8000' has been blocked by CORS policy:
No 'Access-Control-Allow-Origin' header is present on the requested resource.

同じVMの中なのに、ポートが違うだけで止められます。 前回と同じ現象です。

ただし今回は、サーバーが自分のものです。

ヘッダーを1行足す

server.js の createServer の一番上(console.log の直後)に足します。

  res.setHeader("Access-Control-Allow-Origin", "*");

立て直して、もう一度 Console で fetch してください。

(4) [{…}, {…}, {…}, {…}]

通りました。 ブラウザは何も変えていません。サーバーが「渡していいよ」と名乗っただけです。

Access-Control-Allow-Origin は「誰に渡していいか」の宣言です。 * は「どこからでもよい」。学習中はこれで構いませんが、本番で * にしてはいけません。 誰のサイトからでもあなたのAPIを呼べる、という意味になります。本番では呼ばせたいオリジンだけを書きます。

res.setHeader("Access-Control-Allow-Origin", "https://obmes.com");

[スクリーンショット: 02_cors解除.png] Console で fetch が成功し、配列が返っている画面を撮ってください。前回のCORSエラーの画面と並べると、何が変わったのかが一目で分かります。

POST は、それだけでは通らない

GETは通りました。POSTを試してください。

fetch("http://192.168.226.50:3000/api/tasks", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ title: "ブラウザから追加" }),
})
  .then((r) => r.json())
  .then(console.log)
  .catch((e) => console.error("失敗:", e));

また止められます。 そしてVM側のターミナルを見ると、見覚えのない行が出ています。

OPTIONS /api/tasks

POST を送ったのに、届いたのは OPTIONS です。

これが「プリフライト(事前確認)」です。

ブラウザは、危険かもしれないリクエストを、いきなり送りません。 先に OPTIONS で 「このオリジンから、このメソッドと、このヘッダーで送ってもいいですか」と聞きに行きます。 許可が返ってきて初めて、本物のリクエストを送ります。

単純な GET では起きません。Content-Type: application/json を付けた時点で「単純ではない」判定になり、事前確認が入ります。

「POSTだけ通らない」の原因は、ほぼこれです。

答えてやります。 さきほどの setHeader の下に足します。

  res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
  res.setHeader("Access-Control-Allow-Headers", "Content-Type");

  if (req.method === "OPTIONS") {
    res.writeHead(204);   // 204 = 中身は無いが、成功
    res.end();
    return;
  }

立て直して、もう一度 POST してください。 通ります。ターミナルにはこう出ます。

OPTIONS /api/tasks
POST /api/tasks

2回来ています。 1回目が事前確認、2回目が本番です。「1回しか送っていないのに2行出る」のは正常です。

④ Express で書き直す

ここまで全部、標準の http だけで書きました。 その上で道具を入れます。

順番が逆だと意味がありません。 最初から Express を使うと、どこまでが Express の機能で、どこからが HTTP の決まりなのかが分からなくなります。 いま入れるのは、面倒だと分かっている作業を減らすためです。

bash
$ cd ~/server
$ npm init -y
$ npm install express

npm の回でやったとおり、package.json と node_modules/ ができます。

bash
$ ls -la
$ cat package.json

別ファイルに書きます。 見比べたいので、server.js は残します。

bash
$ nano app.js
const express = require("express");
const app = express();

let tasks = [
  { id: 1, title: "Linuxのコマンドを覚える", done: true },
  { id: 2, title: "サーバーを立てる", done: true },
  { id: 3, title: "APIを作る", done: false },
];

// 本文をJSONとして読む(これが req.body を作っている)
app.use(express.json());

// CORS
app.use((req, res, next) => {
  res.setHeader("Access-Control-Allow-Origin", "*");
  res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
  res.setHeader("Access-Control-Allow-Headers", "Content-Type");
  if (req.method === "OPTIONS") return res.sendStatus(204);
  next();
});

app.get("/api/tasks", (req, res) => {
  res.json(tasks);
});

app.post("/api/tasks", (req, res) => {
  if (!req.body.title) {
    return res.status(400).json({ error: "title は必須です" });
  }
  const task = { id: tasks.length + 1, title: req.body.title, done: false };
  tasks.push(task);
  res.status(201).json(task);
});

app.listen(3000, "0.0.0.0", () => {
  console.log("http://0.0.0.0:3000/ で待っています");
});

server.js を止めてから動かします(同じ3000番なので、両方は動きません)。

bash
$ node app.js

さっきと同じ curl が、そのまま通ります。

bash
$ curl -s http://localhost:3000/api/tasks | jq
$ curl -s -X POST http://localhost:3000/api/tasks \
    -H "Content-Type: application/json" -d '{"title":"Expressで書き直した"}' | jq

何が減ったのか

動きは同じです。減ったのは手間です。

やっていたこと生の httpExpress
メソッドとパスの分岐if を積むapp.get("/api/tasks", ...)
本文の組み立てreq.on("data") を自分で書くexpress.json() が req.body を作る
JSONで返すwriteHead + JSON.stringify + endres.json(...)
ステータスを変えるwriteHead(400, {...})res.status(400)
404自分で最後に書く書かなくても返る

express.json() の中身は、さっき手で書いた req.on("data") とほぼ同じです。魔法ではなく、代わりに書いてくれているだけです。

app.use() は「全部のリクエストが通る場所」です。CORSのヘッダーをここに置いたのは、GETにもPOSTにも同じものを付けたいからです。 next() を呼ぶと次へ進み、呼ばないとそこで止まります。認証を差し込むのも、この場所です(第5段階の後半でやります)。

res.json() は Content-Type: application/json を自動で付けます。 さっき手で書いた名乗りです。 付け忘れる余地がなくなる、というのがライブラリを使う一番の利点かもしれません。

⑤ 再起動すると消える

最後に、この作りの限界を確かめます。

bash
$ curl -s -X POST http://localhost:3000/api/tasks \
    -H "Content-Type: application/json" -d '{"title":"消えるか試す"}' | jq
$ curl -s http://localhost:3000/api/tasks | jq 'length'
4

Ctrl + C で止めて、立て直します。

bash
$ node app.js
bash
$ curl -s http://localhost:3000/api/tasks | jq 'length'
3

戻っています。

tasks はただの変数なので、プロセスが死ねば消えます。 サーバーとは何かの回で「メモリに置く」と書いたのは、こういう意味でした。

置き場消えるタイミング
変数(いまここ)プロセスを止めたら消える
ファイルディスクが壊れるまで残る
データベース残る。しかも複数から同時に読み書きできる

「データベースが要る理由」は、ここで初めて実感できます。 先に「DBを使いましょう」と言われても、何が困るのかが分からないからです。

次回、ここをデータベースに置き換えます。

つまずいたところ

症状原因
req.body が undefined生のNodeでは自分で組み立てる。Expressなら express.json() を忘れている
GETは通るのにPOSTだけCORSで落ちるプリフライト(OPTIONS)に答えていない
EADDRINUSEserver.js と app.js を両方動かしている
直したのに変わらないCtrl + C で止めて立て直していない / systemd の myserver が動いたまま
サーバーごと落ちるJSON.parse を try / catch で囲っていない

後片づけ

完成したものを常駐させるなら、前回のサービスの ExecStart を app.js に向け直します。

bash
$ sudo nano /etc/systemd/system/myserver.service
ExecStart=/home/ユーザー名/.nvm/versions/node/v22.14.0/bin/node /home/ユーザー名/server/app.js
bash
$ sudo systemctl daemon-reload
$ sudo systemctl restart myserver
$ systemctl status myserver

やめるなら、開けたポートを閉じます。

bash
$ sudo systemctl disable --now myserver
$ sudo ufw delete allow 3000/tcp
$ sudo ufw delete allow 8000/tcp

~/server/ は残してください。 次回、tasks をデータベースに移します。

まとめ

  • APIは「JSONを返すHTTP」でしかない。 前回の /time が、もうAPIだった
  • Content-Type: application/json は名乗り。 中身は変わらないが、受け取る側の扱いが変わる
  • 生のNodeでは本文は勝手に来ない。 HTTPの本文は分割して届くので、req.on("data") でつなげる
  • JSON.parse は try / catch で囲む。 囲まないと、壊れた文字列1つでサーバーが落ちる
  • 400番台は「送られてきた内容がおかしい」、500番台は「こちらが壊れている」
  • CORSはサーバー側で解除する。 Access-Control-Allow-Origin を返すだけ。フロントを何度書き直しても直らない
  • * は本番で使わない。 誰のサイトからでも呼べる、という意味になる
  • POSTだけ通らないのはプリフライト。 OPTIONS に 204 で答える。1回のPOSTでログが2行出るのは正常
  • Express は魔法ではない。 express.json() は手で書いた req.on("data") と同じことをしている
  • メモリに置いたデータは、プロセスを止めれば消える。 これがデータベースが要る理由

参考リンク


次に読む

この記事は 【第5段階】バックエンドとデータベース の 2 / 29 本目です。

記事
← 前の記事サーバーとは待ち続けるプログラム — 手で書いて確かめる
→ 次の記事プロセスを止めても消えない場所 — MySQLとSQLの基本

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

Backend›APIs
  • REST(JSON を返す HTTP として作る)
  • CORS(サーバー側で許可する)
  • Node.js — Express

この記事は、上の項目を実際に手を動かして確かめる回です。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次