ENGINEERING

30分でできる！非エンジニアのためのAPI超入門：身近なサービスからWebの裏側まで

APIは異なるソフトウェア間の情報交換を可能にする技術であり、TypeScriptとNode.jsを使って30分でシンプルなAPIを構築する方法を紹介。基本的な概念からHTTPとREST APIの基礎、CRUD操作の実装までを学び、API開発の楽しさと可能性を体験できる内容です。

2025-08-19
media

はじめに：APIはあなたの生活をどう変える？そして、なぜ今「APIを作る」のか？

スマートフォンで天気予報をチェックしたり、地図アプリで目的地までのルートを検索したり、SNSで友人とコミュニケーションを取ったり。これら日々の生活を便利にしているサービスの裏側には、「API」という技術が深く関わっています。

APIは「Application Programming Interface」の略で、異なるソフトウェアやアプリケーション同士が情報をやり取りするための「窓口」や「仲介役」のようなものです。私たちは普段、意識せずともAPIの恩恵を受けています。

「APIを作る」と聞くと、なんだか難しそう、エンジニアだけがやるもの、と感じるかもしれません。しかし、APIを自分で作ってみることは、Webサービスがどのように動いているのかを深く理解する素晴らしい機会になります。そして、簡単なツールを自分で作れるようになるなど、あなたのデジタルライフをさらに豊かにする可能性を秘めているのです。

本記事では、プログラミングの知識が少ない方でも、TypeScriptとNode.jsを使ってわずか30分でシンプルなAPIを構築する体験を提供します。APIの基本的な概念から、Webの「会話」のルールであるHTTPとREST APIの基礎まで、手を動かしながら楽しく学んでいきましょう！

APIって何？超入門：レストランのウェイターに例えてみよう

APIとは、異なるソフトウェアやアプリケーション同士が情報をやり取りするための「窓口」や「仲介役」のようなものです。この概念を理解するために、身近な例で考えてみましょう。

レストランのウェイターに例えるAPI

あなたがレストランでお腹を空かせているとします。あなたは直接キッチンに行って料理を作ることはできませんよね。そこで、あなたはウェイターを呼び、メニューを見て「〇〇をください」と注文します。

この時、

  • あなた：情報や機能を利用したい「アプリケーションA」（例：天気予報アプリ）
  • ウェイター：API
  • キッチン：情報や機能を提供したい「アプリケーションB」（例：気象庁のデータサーバー）
  • 注文（「〇〇をください」）：「アプリケーションA」から「アプリケーションB」へのリクエスト
  • 料理（「お待たせしました、〇〇です」）：「アプリケーションB」から「アプリケーションA」へのレスポンス

このように、ウェイター（API）があなたの注文（リクエスト）をキッチン（アプリケーションB）に伝え、キッチンが作った料理（レスポンス）をあなた（アプリケーションA）に届けてくれることで、あなたはキッチンの内部構造を知らなくても、美味しい料理（情報や機能）を受け取ることができます。

APIの基本的な役割は、「異なるシステム間の連携をスムーズにし、必要な情報や機能を安全に、効率的にやり取りできるようにすること」と理解しておけば大丈夫です。

「30分で作る」ための準備：Node.jsとTypeScriptを整えよう

APIを実際に作る前に、まずは開発環境を整えましょう。今回は、Web開発で広く使われている「Node.js」と、JavaScriptに型安全性を加える「TypeScript」を使います。

1. Node.jsとnpmをインストールしよう

Node.jsは、JavaScriptをWebブラウザの外で実行するための環境です。npm（Node Package Manager）は、Node.jsのパッケージ（ライブラリやツール）を管理するためのツールで、Node.jsをインストールすると一緒についてきます。

以下の手順でインストールできます。

  1. Node.jsの公式サイトにアクセス: https://nodejs.org/ja
  2. 「LTS (長期サポート版)」と書かれたボタンをクリックして、インストーラーをダウンロードします。
  3. ダウンロードしたインストーラーを実行し、画面の指示に従ってインストールを進めます。特に設定を変更する必要はありません。

インストールが完了したら、コマンドプロンプト（Windows）またはターミナル（Mac/Linux）を開き、以下のコマンドを入力して、バージョンが表示されることを確認してください。

node -v
npm -v

バージョンが表示されれば、インストールは成功です！

2. プロジェクトの準備とTypeScriptの初期設定

次に、APIを作るためのプロジェクトフォルダを作成し、TypeScriptを使えるように設定します。

  1. 新しいフォルダを作成: 任意の場所に、例えばmy-first-apiという名前のフォルダを作成します。
  2. コマンドプロンプト/ターミナルでフォルダに移動: 作成したフォルダに移動します。 bash cd path/to/my-first-api
  3. npmプロジェクトを初期化: 以下のコマンドを実行し、package.jsonファイルを作成します。これは、プロジェクトの情報や使用するパッケージを管理するためのファイルです。質問はすべてEnterでスキップして大丈夫です。 bash npm init -y
  4. TypeScriptをインストール: 以下のコマンドでTypeScriptをインストールします。 bash npm install -D typescript @types/node
    • Dは開発時のみ必要なパッケージであることを示します。
    • @types/nodeは、Node.jsの機能（ファイル操作など）をTypeScriptで使うための「型定義ファイル」です。TypeScriptは型を重視するため、このようなファイルが必要になります。
  5. TypeScriptの設定ファイルを作成: 以下のコマンドを実行し、tsconfig.jsonファイルを作成します。これは、TypeScriptのコンパイル（TypeScriptのコードをJavaScriptに変換すること）に関する設定を行うファイルです。 bash npx tsc --init
    • npxは、インストールしたパッケージのコマンドを実行するためのツールです。

これで、TypeScriptでAPIを開発するための基本的な準備が整いました。次のステップでは、実際にコードを書いてAPIを動かしてみましょう！

初めてのAPI構築：TypeScriptとExpressで超シンプルなAPIを作ってみよう

準備が整ったところで、いよいよAPIを構築していきます。今回は、Node.jsでWebアプリケーションやAPIを簡単に作るためのフレームワーク「Express.js」を使います。

1. Express.jsをインストール

まずはExpress.jsをプロジェクトにインストールしましょう。コマンドプロンプト/ターミナルで、プロジェクトフォルダ（my-first-api）にいることを確認して、以下のコマンドを実行します。

npm install express @types/express
  • expressがExpress.js本体です。
  • @types/expressは、Express.jsをTypeScriptで使うための型定義ファイルです。

2. 「Hello, API!」を返すAPIを作ろう

プロジェクトフォルダの直下にsrcというフォルダを作成し、その中にindex.tsというファイルを作成してください。最終的なファイル構成は以下のようになります。

my-first-api/
├── node_modules/
├── src/
│   └── index.ts
├── package.json
├── package-lock.json
└── tsconfig.json

そして、src/index.tsに以下のコードを記述してください。

import express from 'express';

// Expressアプリケーションを作成
const app = express();
const port = 3000; // APIが動作するポート番号

// ルート（'/'）へのGETリクエストに対する処理
app.get('/', (req, res) => {
  res.send('Hello, API!'); // 「Hello, API!」というテキストを返す
});

// 指定したポートでサーバーを起動
app.listen(port, () => {
  console.log(`APIサーバーが http://localhost:${port} で起動しました`);
});

コードの解説

  • import express from 'express';: Express.jsを使うための準備です。
  • const app = express();: Expressアプリケーションの本体を作成しています。これがAPIの司令塔になります。
  • const port = 3000;: APIが待ち受けるポート番号を設定しています。Webサイトでいう「住所」のようなものです。今回は3000番ポートを使います。
  • app.get('/', (req, res) => { ... });: ここがAPIの「窓口」の設定です。
    • app.get()は、WebブラウザからURLにアクセスするような「情報を取得する（GET）」リクエストを受け付ける設定です。
    • '/'は、APIの「パス」です。今回は「http://localhost:3000/」という一番シンプルなURLにアクセスしたときに動くように設定しています。
    • (req, res) => { ... }は、リクエストが来たときに実行される処理です。reqはリクエストの情報、resはレスポンスを返すためのオブジェクトです。
    • res.send('Hello, API!');は、クライアント（Webブラウザなど）に対して「Hello, API!」というテキストを返す、という指示です。
  • app.listen(port, () => { ... });: これでAPIサーバーを起動します。指定したポート（今回は3000番）でリクエストを待ち受ける状態になります。サーバーが起動したら、コンソールにメッセージが表示されます。

3. APIを起動して動作確認

APIを起動するには、TypeScriptのコードをJavaScriptにコンパイルし、Node.jsで実行する必要があります。package.jsonに便利なスクリプトを追加しましょう。

package.jsonを開き、"scripts": { ... }の箇所を以下のように編集してください。

{
  "name": "my-first-api",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "npm run build && npm run start"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "@types/node": "^20.x.x",
    "@types/express": "^4.x.x",
    "typescript": "^5.x.x"
  },
  "dependencies": {
    "express": "^4.x.x"
  }
}
  • "build": "tsc": TypeScriptのコードをJavaScriptにコンパイルするコマンドです。コンパイルされたJavaScriptファイルは、デフォルトでdistフォルダに作成されます。
  • "start": "node dist/index.js": コンパイルされたJavaScriptファイルを実行するコマンドです。
  • "dev": "npm run build && npm run start": buildコマンドを実行した後、startコマンドを実行する、という一連の流れをまとめて実行するコマンドです。

これで準備は完了です！コマンドプロンプト/ターミナルで以下のコマンドを実行して、APIサーバーを起動しましょう。

npm run dev

以下のようなメッセージが表示されれば成功です。

APIサーバーが http://localhost:3000 で起動しました

動作確認

APIサーバーが起動したら、以下の方法で動作を確認できます。

  1. Webブラウザで確認: Webブラウザを開き、アドレスバーにhttp://localhost:3000/と入力してEnterキーを押します。「Hello, API!」というテキストが表示されれば成功です。
  2. curlコマンドで確認: コマンドプロンプト/ターミナルをもう一つ開き、以下のコマンドを実行します。 bash curl http://localhost:3000/ 「Hello, API!」というテキストが返ってくれば成功です。

これで、あなたはTypeScriptとNode.js、Expressを使って、初めてのAPIを構築し、動作させることに成功しました！わずか30分で、Webの裏側で動くAPIの基本的な仕組みを体験できたはずです。

HTTPとREST APIの基礎を実践で理解する

先ほど作成した「Hello, API!」を返すAPIは、非常にシンプルですが、Webの「会話」の基本的なルールであるHTTPとREST APIの概念を理解するのに役立ちます。

HTTP：Web上の「会話」の共通言語

HTTP（Hypertext Transfer Protocol）は、WebブラウザとWebサーバーの間で情報をやり取りするための通信規約（プロトコル）です。あなたがWebサイトを閲覧する際、ブラウザはHTTPを使ってWebサーバーに「このページを見せてください」とリクエストを送り、サーバーはHTTPを使って「はい、どうぞ」とページの情報（HTML、画像など）をレスポンスとして返しています。

APIも、このHTTPという共通言語を使って情報のやり取りを行います。先ほどのAPIにhttp://localhost:3000/とアクセスした際、あなたのブラウザはAPIサーバーに対してHTTPのGETメソッドを使ってリクエストを送っていました。

HTTPには、情報のやり取りの方法を示すいくつかの「メソッド」があります。代表的なものは以下の通りです。

  • GET: サーバーから情報を「取得」する際に使われます。（例：Webページを見る、天気予報のデータを取得する）
  • POST: サーバーに新しい情報を「送信」する際に使われます。（例：フォームを送信する、新しい記事を投稿する）
  • PUT: サーバーの既存の情報を「更新」する際に使われます。
  • DELETE: サーバーの情報を「削除」する際に使われます。

これらのメソッドを使い分けることで、Web上での様々な情報のやり取りが実現されています。

REST API：Webサービスの「設計思想」

REST（Representational State Transfer）は、Webサービスを設計する上での「考え方」や「原則」のようなものです。RESTの原則に従って作られたAPIを「REST API」と呼びます。

REST APIの重要な原則の一つに「リソース指向」という考え方があります。これは、Web上のあらゆるものを「リソース」（資源）として捉え、そのリソースに対してHTTPメソッドを使って操作を行う、というものです。

例えば、商品情報を扱うAPIであれば、商品一つ一つが「リソース」となります。そして、

  • GET /products：全ての商品情報を取得
  • GET /products/123：IDが123の商品情報を取得
  • POST /products：新しい商品情報を作成
  • PUT /products/123：IDが123の商品情報を更新
  • DELETE /products/123：IDが123の商品情報を削除

といった形で、URL（リソースの場所）とHTTPメソッド（操作の種類）を組み合わせることで、直感的にAPIの機能が理解できるよう設計されています。

先ほど作成したAPIは、http://localhost:3000/というルートパスにGETリクエストを送ると「Hello, API!」というテキストを返す、というシンプルなものでしたが、これも「/というリソースに対してGET操作を行う」というRESTの考え方に沿っています。

多くのモダンなWebサービスやアプリは、このREST APIの設計思想に基づいて構築されており、シンプルで分かりやすく、拡張性が高いというメリットがあります。

さらに一歩進む：簡単なデータ管理APIを作ってみよう（CRUD操作の導入）

「Hello, API!」を返すだけのAPIは作れましたが、実際のAPIはもっと複雑なデータを扱います。ここでは、簡単な商品リストを管理するAPIを例に、データの作成（Create）、読み取り（Read）、更新（Update）、削除（Delete）という「CRUD」操作を実装してみましょう。データベースは使わず、APIサーバーが起動している間だけデータを保持する「インメモリ」で実装します。

1. 商品データの型定義

まず、扱う商品データの「型」をTypeScriptで定義します。src/index.tsの先頭に以下のコードを追加してください。

interface Product {
  id: string;
  name: string;
  price: number;
  description?: string; // オプション（あってもなくても良い）
}

// 仮のデータストア（インメモリ）
let products: Product[] = [
  { id: '1', name: 'りんご', price: 150, description: '青森県産' },
  { id: '2', name: 'みかん', price: 100, description: '愛媛県産' },
];
  • interface Product: 商品が持つべき情報（id, name, price, description）とその型を定義しています。description?のように?をつけると、その項目は必須ではなくなります。
  • let products: Product[] = [...]: Product型のオブジェクトを複数格納できる配列productsを定義し、初期データとして2つの商品を入れています。これが、今回のAPIの「データベース」の代わりになります。

2. JSONデータの送受信を可能にする

APIでデータを送受信する際には、JSON形式がよく使われます。ExpressでJSONデータを扱えるようにするために、以下の行をconst app = express();の直後に追加してください。

app.use(express.json()); // JSON形式のリクエストボディを解析するミドルウェア

3. CRUD操作のエンドポイントを追加

app.get('/')の定義の下に、以下のエンドポイントを追加していきます。

全ての商品を取得する（GET /products）

// 全ての商品を取得
app.get('/products', (req, res) => {
  res.json(products); // products配列をJSON形式で返す
});
  • res.json(products): res.send()の代わりにres.json()を使うことで、JavaScriptのオブジェクトを自動的にJSON形式に変換して返してくれます。

特定の商品を取得する（GET /products/:id）

// 特定の商品を取得
app.get('/products/:id', (req, res) => {
  const { id } = req.params; // URLのパスパラメータからidを取得
  const product = products.find(p => p.id === id); // idに一致する商品を探す

  if (product) {
    res.json(product);
  } else {
    res.status(404).send('Product not found'); // 商品が見つからない場合は404エラーを返す
  }
});
  • req.params: URLのパスに含まれる動的な値（例：/products/1の1）を取得できます。:idとすることで、idという名前で値を取得できます。
  • products.find(): 配列の中から条件に合う要素を探すJavaScriptのメソッドです。
  • res.status(404).send(): HTTPステータスコードを404（Not Found）に設定し、エラーメッセージを返しています。

新しい商品を作成する（POST /products）

// 新しい商品を作成
app.post('/products', (req, res) => {
  const newProduct: Product = {
    id: String(products.length + 1), // 仮のIDを生成
    ...req.body, // リクエストボディから商品情報を取得
  };
  products.push(newProduct);
  res.status(201).json(newProduct); // 作成された商品を201ステータス（Created）で返す
});
  • req.body: クライアントから送られてきたJSONデータ（リクエストボディ）を取得できます。
  • id: String(products.length + 1): 今回は簡易的に、現在の商品の数に1を足したものをIDとしています。実際にはUUIDなどユニークなIDを生成します。
  • ...req.body: スプレッド構文を使って、リクエストボディのプロパティをnewProductにコピーしています。
  • res.status(201).json(): HTTPステータスコードを201（Created）に設定し、作成された商品を返しています。

既存の商品を更新する（PUT /products/:id）

// 既存の商品を更新
app.put('/products/:id', (req, res) => {
  const { id } = req.params;
  const updatedProductData: Product = req.body;

  const index = products.findIndex(p => p.id === id); // idに一致する商品のインデックスを探す

  if (index !== -1) {
    products[index] = { ...products[index], ...updatedProductData, id }; // 既存の情報を上書き
    res.json(products[index]);
  } else {
    res.status(404).send('Product not found');
  }
});
  • products.findIndex(): 配列の中から条件に合う要素のインデックスを探すJavaScriptのメソッドです。
  • index !== -1: findIndexは要素が見つからない場合1を返します。
  • { ...products[index], ...updatedProductData, id }: 既存の商品情報に、更新データと元のIDをマージして上書きしています。

特定の商品を削除する（DELETE /products/:id）

// 特定の商品を削除
app.delete('/products/:id', (req, res) => {
  const { id } = req.params;
  const initialLength = products.length;

  products = products.filter(p => p.id !== id); // idに一致しない商品だけを残す

  if (products.length < initialLength) {
    res.status(204).send(); // 削除成功時は204ステータス（No Content）を返す
  } else {
    res.status(404).send('Product not found');
  }
});
  • products.filter(): 配列から条件に合う要素を除外した新しい配列を作成します。
  • res.status(204).send(): 削除が成功し、返すコンテンツがない場合に使うステータスコードです。

動作確認

APIサーバーを再起動（Ctrl+Cで停止し、再度npm run dev）した後、PostmanやInsomniaといったAPIテストツール、またはcurlコマンドを使って動作を確認してみましょう。

例: curlコマンドでの動作確認

  • 全ての商品を取得 (GET)
    • bash curl http://localhost:3000/products
    • 初期データの商品リストが返ってくるはずです
  • 新しい商品を作成 (POST)
    • bash curl -X POST -H "Content-Type: application/json" -d '{"name":"バナナ","price":200,"description":"フィリピン産"}' http://localhost:3000/products
    • 新しい商品が追加され、その情報が返ってくるはずです
  • 特定の商品を取得 (GET)
    • bash curl http://localhost:3000/products/1
    • IDが1の商品情報が返ってくるはずです
  • 特定の商品を更新 (PUT)
    • bash curl -X PUT -H "Content-Type: application/json" -d '{"price":180}' http://localhost:3000/products/1
    • IDが1の商品の価格が更新され、更新後の情報が返ってくるはずです
  • 特定の商品を削除 (DELETE)
    • bash curl -X DELETE http://localhost:3000/products/1 何も返ってきませんが、ステータスコード204が返っていれば成功です。再度GET /productsで確認すると、商品が減っているはずです

これで、あなたは簡単なデータ管理機能を持つAPIをTypeScriptとExpressで構築できました！

API活用の未来と次のステップ

今回、あなたはTypeScriptとNode.js、Expressを使って、シンプルなAPIを構築する体験をしました。これは、Webサービスの裏側で何が起きているのかを理解するための第一歩です。APIは、今後も私たちの生活やビジネスにおいて、その重要性を増していくでしょう。

AI（人工知能）やIoT（モノのインターネット）の進化に伴い、様々なデバイスやサービスがAPIを通じて連携し、より高度でパーソナライズされた体験が提供されるようになります。例えば、スマートスピーカーがあなたの好みを学習し、APIを通じて最適な音楽を再生したり、スマート家電があなたの生活パターンを把握し、APIを通じて自動で最適な環境を整えたりする未来が、すでに現実のものとなりつつあります。

ビジネスにおいても、APIエコノミーと呼ばれる、APIを通じて企業間でサービスやデータを連携し、新たな価値を創造する動きが加速しています。APIは、単なる技術的なインターフェースではなく、ビジネスを成長させ、社会をより豊かにするための重要な基盤となっているのです。

次のステップ

今回作成したAPIは非常にシンプルですが、ここからさらに発展させるためのヒントをいくつかご紹介します。

  • データベース連携: 今回はインメモリでデータを管理しましたが、永続的にデータを保存するためには、MySQLやPostgreSQL、MongoDBなどのデータベースと連携する必要があります。TypeORMやPrismaといったORM（Object-Relational Mapper）を使うと、TypeScriptでデータベース操作を簡単に行えます。
  • 認証・認可: 実際のAPIでは、誰がAPIを利用できるのか、どのような操作を許可するのかを制御するための認証（Authentication）と認可（Authorization）の仕組みが必要です。JWT（JSON Web Token）などがよく使われます。
  • エラーハンドリングの強化: 今回は簡易的なエラー処理でしたが、よりユーザーフレンドリーで堅牢なAPIにするためには、詳細なエラーメッセージを返したり、エラーの種類に応じた適切なHTTPステータスコードを返したりする仕組みが必要です。
  • バリデーション: クライアントから送られてくるデータが正しい形式であるかを確認する「バリデーション」も重要です。joiやclass-validatorなどのライブラリが役立ちます。
  • より高度なフレームワーク: NestJSやFastifyなど、Expressよりも高機能で開発効率を向上させるフレームワークも存在します。プロジェクトの規模や要件に応じて検討してみるのも良いでしょう。
  • フロントエンドとの連携: 今回作ったAPIはバックエンドです。このAPIを使って、Webサイトやモバイルアプリなどのフロントエンドを開発することで、より実践的なアプリケーションを構築できます。

API開発の世界は奥深く、学ぶことはたくさんありますが、今回の体験がその第一歩となることを願っています。TypeScriptとNode.jsは、Web開発の現場で非常に需要が高く、習得することであなたのキャリアの可能性を大きく広げることができるでしょう。

まとめ：APIを作る楽しさを体験しよう！

本記事では、APIの基本的な概念から、TypeScriptとNode.js、Expressを使ったAPIの構築方法、そしてHTTPとREST APIの基礎までを解説しました。

「APIを作る」という体験は、Webサービスがどのように動いているのか、データがどのようにやり取りされているのかを、より深く理解するための貴重な一歩です。プログラミングの経験が少ない方でも、わずか30分でシンプルなAPIを動かすことができたのではないでしょうか。

API開発の世界は広大ですが、今回の体験を通じて、その楽しさや可能性を感じていただけたなら幸いです。ぜひ、この一歩をきっかけに、さらにWeb開発の世界を探求してみてください。あなたのアイデアを形にするための強力なツールとして、API開発のスキルが役立つことを願っています。