Node.js、Express、TypeScript による RESTful API の構築
Express、TypeScript、PostgreSQL で管理者向けユーザープロフィール API を構築し、HTTP 経由でプロフィールを作成、取得、更新、削除します。ローカルのテストトークンを生成し、API を再起動してプロフィールが残ることを検証します。この API はプロフィールデータを保存しますが、ログインやパスワードの保存は実装しません。
はじめに
この API は、署名付きアクセストークンを持つ信頼された管理者を対象とします。プロフィールの取得には profiles:read スコープ、作成、編集、削除には profiles:write が必要です。これらのスコープはすべてのプロフィールへのアクセスを許可します。ユーザー自身が操作するセルフサービス API ではありません。スコープは信頼された発行者が割り当てます。リクエストボディで認可上の ID やロールを選択することはできません。
システム要件
Linux 上の Bash、Node.js 24 または 26 の LTS の最新パッチ、cURL、稼働中の Docker Engine を使用します。このサンプル全体は、2026年11月6日に Node.js 24.22.2 と 26.13.0 でテストしました。選択した LTS 系列を最新に保ってください。10月のセキュリティリリースは、それ以前のパッチに代わるものです。
開始前に Corepack をインストールしてください。Node.js 26 には同梱されていません。Corepack は、Yarn のグローバルインストールなしで、プロジェクトに固定された Yarn 4.12.0 を実行します。このサンプルでは PostgreSQL 17.11、Express 5.2.1、TypeORM 1.1.1、TypeScript 5.9.3 を使用します。Express 5 は、ルートハンドラーの Promise の拒否をエラーミドルウェアに渡します。
後述のローカル署名ツールは、発行者、対象者、サブジェクト、有効期限、スペース区切りのスコープを含む RS256 JWT を発行します。ID プロバイダーのアカウントなしで、実際の署名検証を試せます。秘密鍵を持つ人は誰でも管理者アクセス権を付与できるため、このループバックでのデモにのみ使用してください。
環境のセットアップ
セットアップ手順は順番に実行し、エラーが発生したら中止してください。stack-api がすでに存在する場合は、上書きせず別のディレクトリを選びます。サブシェルを使うことで、セットアップに失敗しても元のディレクトリにとどまります。
(
mkdir stack-api && cd stack-api &&
mkdir -p src/config src/controllers src/middleware src/models src/routes src/local
) && cd stack-api
次の内容全体を package.json として保存します。
{
"name": "stack-api",
"private": true,
"type": "module",
"packageManager": "yarn@4.12.0",
"scripts": {
"build": "tsc --project tsconfig.json",
"start": "node dist/index.js"
},
"dependencies": {
"express": "5.2.1",
"helmet": "8.3.0",
"jose": "6.2.12",
"pg": "8.23.0",
"reflect-metadata": "0.2.2",
"typeorm": "1.1.1",
"zod": "3.25.76"
},
"devDependencies": {
"@types/express": "5.0.6",
"@types/node": "24.10.1",
"typescript": "5.9.3"
}
}
プロジェクトローカルの node_modules を使用するため、.yarnrc.yml を保存します。
nodeLinker: node-modules
enableGlobalCache: false
enableTelemetry: false
ignorePath: true
injectEnvironmentFiles: []
tsconfig.json を作成します。types と typeRoots を明示すると、親プロジェクトの無関係なアンビエント型をコンパイラーが取り込むのを防げます。
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"outDir": "./dist",
"rootDir": "./src",
"types": ["node"],
"typeRoots": ["./node_modules/@types"],
"strict": true,
"esModuleInterop": true,
"experimentalDecorators": true,
"emitDecoratorMetadata": true
},
"include": ["src/**/*.ts"]
}
続いてインストールします。空の yarn.lock により、ワークスペース内でもこのディレクトリを独立した Yarn プロジェクトとして扱えます。NODE_OPTIONS をクリアすると、親プロジェクトの
Plug’n’Play ローダーがこれらのコマンドに注入されるのを防げます。
touch yarn.lock && NODE_OPTIONS='' corepack yarn install
生成されたロックファイルは、以降のインストールのために保持してください。ローカルの署名鍵やデータベース認証情報をソース管理に含めないでください。自分のプロジェクトでは .local/ を除外します。
プロジェクト構成
src/
├── config/database.ts
├── controllers/userController.ts
├── middleware/errorHandler.ts
├── middleware/auth.ts
├── models/User.ts
├── routes/userRoutes.ts
├── local/createKeys.ts
├── local/issueToken.ts
├── app.ts
└── index.ts
データベース接続のセットアップ
公式 PostgreSQL イメージで使い捨てのデータベースを起動します。Docker がループバック上の空きポートを割り当てます。以下のパスワードは、このローカルサンプル専用です。コンテナのデータベースユーザーはスーパーユーザーのため、デプロイ先のアプリケーションには不適切です。
: "${DB_CONTAINER:=stack-api-db-${RANDOM}-${RANDOM}}"
docker run --detach --name "$DB_CONTAINER" \
--publish 127.0.0.1::5432 \
--tmpfs /var/lib/postgresql/data:rw,size=256m \
--env POSTGRES_USER=profiles --env POSTGRES_DB=profiles \
--env POSTGRES_PASSWORD=local-only-password postgres:17.11-bookworm
TCP 接続の準備ができているか確認し、試行間に一秒の間隔を置いて 30 回再試行します。このブロックが成功した場合にのみ続行してください。
(
for attempt in {1..30}; do
if docker exec "$DB_CONTAINER" pg_isready -h 127.0.0.1 -U profiles -d profiles; then
exit 0
fi
sleep 1
done
printf 'PostgreSQL did not become ready; inspect docker logs.\n' >&2
exit 1
)
このターミナルは開いたままにしてください。後の設定と後片付けで DB_CONTAINER を使用します。API の再起動中もデータベースは利用できますが、データベースコンテナを停止すると一時データは失われます。これは意図的にローカル演習として構成しています。
src/config/database.ts を作成します。
import 'reflect-metadata'
import { DataSource } from 'typeorm'
import { User } from '../models/User.js'
if (!process.env.DATABASE_URL) throw new Error('DATABASE_URL is required')
export const AppDataSource = new DataSource({
type: 'postgres',
url: process.env.DATABASE_URL,
synchronize: process.env.SCHEMA_SYNC === 'development-only',
logging: false,
entities: [User],
})
.js のインポート指定子は、この単独の NodeNext プロジェクトで出力されるファイルを参照します。Node の型除去は TypeORM のデコレーターを変換しないため、TypeScript でコンパイルしてください。デプロイ先のデータベースには、レビュー済みの
TypeORM マイグレーションを使用してください。
ユーザーモデルの作成
src/models/User.ts を作成します。
import { Column, CreateDateColumn, Entity, PrimaryGeneratedColumn } from 'typeorm'
@Entity()
export class User {
@PrimaryGeneratedColumn('uuid')
id!: string
@Column({ type: 'varchar', length: 100 })
name!: string
@Column({ type: 'varchar', length: 254, unique: true })
email!: string
@CreateDateColumn({ type: 'timestamptz' })
createdAt!: Date
}
パスワード列はありません。プロフィールを作成しても、ログインアカウントの作成やアクセス権の付与は行われません。timestamptz は、データベースセッションのタイムゾーンに依存しない時点として作成日時を保存します。
エラー処理ミドルウェア
src/middleware/errorHandler.ts を作成します。リクエストごとに新しいリクエスト ID を生成してください。クライアントのリクエスト ID ヘッダーを監査用識別子として信頼してはいけません。
import { randomUUID } from 'node:crypto'
import type { ErrorRequestHandler, RequestHandler } from 'express'
import { QueryFailedError } from 'typeorm'
import { z, ZodError } from 'zod'
export class AppError extends Error {
constructor(public statusCode: number, message: string) {
super(message)
}
}
export const requestId: RequestHandler = (_req, res, next) => {
res.locals.requestId = randomUUID()
res.setHeader('X-Request-ID', res.locals.requestId)
res.setHeader('Cache-Control', 'no-store')
next()
}
export const errorHandler: ErrorRequestHandler = (error, _req, res, next) => {
if (res.headersSent) {
next(error)
return
}
let status = 500
let message = 'Request failed'
if (error instanceof AppError) {
status = error.statusCode
message = error.message
} else if (error instanceof ZodError) {
status = 400
message = 'Invalid request'
} else if (error instanceof QueryFailedError &&
z.object({ code: z.literal('23505') }).safeParse(error.driverError).success) {
status = 409
message = 'Email is already in use'
} else {
const parsed = z.object({
type: z.enum(['entity.parse.failed', 'entity.too.large']),
}).safeParse(error)
if (parsed.success) {
status = parsed.data.type === 'entity.too.large' ? 413 : 400
message = 'Invalid request body'
}
}
console.error(JSON.stringify({ event: 'request_failed', requestId: res.locals.requestId, status }))
res.status(status).json({ error: message, requestId: res.locals.requestId })
}
src/middleware/auth.ts を作成します。設定した公開鍵、発行者、対象者、アルゴリズムはサーバー側のポリシーです。トークンヘッダーやリクエストパラメーターで置き換えることはできません。jose はこれらの検証オプションを使って署名とクレームを検証します。サーバーは sub、exp、iat を必須とし、発行から 15 分を超えたトークンは、有効期限が先でも拒否します。本番環境の発行者もこれらのクレームを提供する必要があります。
import type { RequestHandler } from 'express'
import { importSPKI, jwtVerify } from 'jose'
import { AppError } from './errorHandler.js'
const { JWT_PUBLIC_KEY, JWT_ISSUER, JWT_AUDIENCE } = process.env
if (!JWT_PUBLIC_KEY || !JWT_ISSUER || !JWT_AUDIENCE) {
throw new Error('JWT verification configuration is required')
}
const verificationKey = await importSPKI(JWT_PUBLIC_KEY, 'RS256')
export function authorize(scope: string): RequestHandler {
return async (req, _res, next) => {
const match = /^Bearer ([A-Za-z0-9_.-]+)$/.exec(req.headers.authorization ?? '')
if (!match) throw new AppError(401, 'Authentication required')
let payload
try {
const verified = await jwtVerify(match[1], verificationKey, {
algorithms: ['RS256'],
issuer: JWT_ISSUER,
audience: JWT_AUDIENCE,
requiredClaims: ['sub', 'exp', 'iat'],
maxTokenAge: '15m',
})
payload = verified.payload
} catch {
throw new AppError(401, 'Invalid access token')
}
if (typeof payload.scope !== 'string' || !payload.scope.split(' ').includes(scope)) {
throw new AppError(403, 'Permission denied')
}
next()
}
}
Express サーバーのセットアップ
src/app.ts を作成します。
import express from 'express'
import helmet from 'helmet'
import { errorHandler, requestId } from './middleware/errorHandler.js'
import { userRoutes } from './routes/userRoutes.js'
export const app = express()
app.disable('x-powered-by')
app.use(requestId)
app.use(helmet())
app.use('/api/v1/users', userRoutes)
app.use((_req, res) => res.status(404).json({
error: 'Not found', requestId: res.locals.requestId,
}))
app.use(errorHandler)
src/index.ts を作成します。
import { once } from 'node:events'
import { z } from 'zod'
import { app } from './app.js'
import { AppDataSource } from './config/database.js'
async function main(): Promise<void> {
const port = z.coerce.number().int().min(1).max(65535).parse(process.env.PORT ?? 3000)
await AppDataSource.initialize()
const server = app.listen(port, '127.0.0.1')
server.requestTimeout = 30_000
server.headersTimeout = 10_000
await once(server, 'listening')
console.log(`Listening on http://127.0.0.1:${port}`)
}
main().catch(async () => {
console.error('API startup failed; check database, JWT settings, and PORT')
if (AppDataSource.isInitialized) await AppDataSource.destroy()
process.exitCode = 1
})
準備完了のメッセージは、PostgreSQL への接続と HTTP ポートのバインド後にのみ表示されます。起動に失敗した場合は、データベースコンテナ、鍵の設定、別のプロセスが PORT を使用していないかを確認してください。見覚えのないプロセスを停止するのではなく、空きポートを選んでください。
ユーザーコントローラー
src/controllers/userController.ts を作成します。厳密なスキーマにより、id、password、role、タイムスタンプなどの余分なフィールドを黙って受け入れず、拒否します。
import type { Request, Response } from 'express'
import { z } from 'zod'
import { AppDataSource } from '../config/database.js'
import { AppError } from '../middleware/errorHandler.js'
import { User } from '../models/User.js'
const profiles = AppDataSource.getRepository(User)
const profileSchema = z.object({
name: z.string().trim().min(1).max(100),
email: z.string().trim().email().max(254).transform((value) => value.toLowerCase()),
}).strict()
const patchSchema = profileSchema.partial().refine((value) => Object.keys(value).length > 0)
const idSchema = z.string().uuid()
export async function getUsers(req: Request, res: Response): Promise<void> {
const query = z.object({
offset: z.coerce.number().int().min(0).max(10000).default(0),
limit: z.coerce.number().int().min(1).max(100).default(20),
}).strict().parse(req.query)
const data = await profiles.find({ skip: query.offset, take: query.limit, order: { id: 'ASC' } })
res.json({ data })
}
export async function getUser(req: Request, res: Response): Promise<void> {
const user = await profiles.findOneBy({ id: idSchema.parse(req.params.id) })
if (!user) throw new AppError(404, 'User not found')
res.json({ data: user })
}
export async function createUser(req: Request, res: Response): Promise<void> {
const { name, email } = profileSchema.parse(req.body)
const user = await profiles.save(profiles.create({ name, email }))
res.location('/api/v1/users/' + user.id).status(201).json({ data: user })
}
export async function updateUser(req: Request, res: Response): Promise<void> {
const id = idSchema.parse(req.params.id)
const fields = patchSchema.parse(req.body)
const result = await profiles.update(id, fields)
if (result.affected === 0) throw new AppError(404, 'User not found')
res.status(204).end()
}
export async function deleteUser(req: Request, res: Response): Promise<void> {
const result = await profiles.delete(idSchema.parse(req.params.id))
if (result.affected === 0) throw new AppError(404, 'User not found')
res.status(204).end()
}
更新と削除は、ボディが空の 204 レスポンスを返します。正規化後のメールアドレスが重複している場合は 409 を返します。取得時には、プロフィールモデルの公開フィールドのみを返します。
ユーザールート
src/routes/userRoutes.ts を作成します。認証は JSON の解析より前に行います。
import { json, Router } from 'express'
import { createUser, deleteUser, getUser, getUsers, updateUser } from '../controllers/userController.js'
import { authorize } from '../middleware/auth.js'
export const userRoutes = Router()
const body = json({ limit: '10kb' })
userRoutes.get('/', authorize('profiles:read'), getUsers)
userRoutes.get('/:id', authorize('profiles:read'), getUser)
userRoutes.post('/', authorize('profiles:write'), body, createUser)
userRoutes.patch('/:id', authorize('profiles:write'), body, updateUser)
userRoutes.delete('/:id', authorize('profiles:write'), deleteUser)
アプリケーションの実行
src/local/createKeys.ts を作成します。新しいプロジェクトごとに一度実行してください。既存の鍵は上書きしません。
import { generateKeyPairSync } from 'node:crypto'
import { mkdir, writeFile } from 'node:fs/promises'
const pair = generateKeyPairSync('rsa', { modulusLength: 2048 })
await mkdir('.local', { mode: 0o700 })
await writeFile('.local/private.pem', pair.privateKey.export({ type: 'pkcs8', format: 'pem' }), {
flag: 'wx', mode: 0o600,
})
await writeFile('.local/public.pem', pair.publicKey.export({ type: 'spki', format: 'pem' }), {
flag: 'wx', mode: 0o600,
})
src/local/issueToken.ts を作成します。このローカルのテスト発行者は、両方の管理者スコープを五分間付与します。API のログインルートではなく、コマンドライン用の補助ツールです。
import { readFile } from 'node:fs/promises'
import { importPKCS8, SignJWT } from 'jose'
const key = await importPKCS8(await readFile('.local/private.pem', 'utf8'), 'RS256')
const token = await new SignJWT({ scope: 'profiles:read profiles:write' })
.setProtectedHeader({ alg: 'RS256' })
.setIssuer('https://local-issuer.example.test')
.setAudience('profile-api')
.setSubject('local-admin')
.setIssuedAt()
.setExpirationTime('5m')
.sign(key)
console.log(token)
TypeScript をコンパイルして鍵を作成します。&& により、コンパイル失敗時に古いビルドが実行されるのを防ぎます。
NODE_OPTIONS='' corepack yarn build && NODE_OPTIONS='' node dist/local/createKeys.js
PostgreSQL を起動したターミナルでサーバーを設定します。JWT_PUBLIC_KEY には、実際の改行を含む PEM テキストが入ります。SCHEMA_SYNC は、この使い捨てデータベースに限りテーブル作成を有効にします。マイグレーションで管理するデプロイ先のデータベースでは、未設定のままにしてください。
DB_ADDRESS="$(docker port "$DB_CONTAINER" 5432/tcp)" &&
LOCAL_PUBLIC_KEY="$(cat .local/public.pem)" &&
export DATABASE_URL="postgresql://profiles:local-only-password@${DB_ADDRESS}/profiles" \
JWT_PUBLIC_KEY="$LOCAL_PUBLIC_KEY" \
JWT_ISSUER='https://local-issuer.example.test' JWT_AUDIENCE='profile-api' \
SCHEMA_SYNC=development-only PORT="${PORT:-3000}"
API をフォアグラウンドで起動します。Listening on http://127.0.0.1:3000、または選択したポートが表示されるまで待ちます。
NODE_OPTIONS='' corepack yarn start
API のテスト
stack-api で二つ目のターミナルを開きます。別のポートを選んだ場合は、こちらでも PORT を設定してください。トークンと返された UUID を引き続き利用できるよう、以下は同じ二つ目のターミナルで実行します。トークンをログやフロントエンドのソースに含めないでください。期限切れのトークンを更新するには、トークンのコマンドを再実行します。
BASE_URL="http://127.0.0.1:${PORT:-3000}"
NEXT_ACCESS_TOKEN="$(NODE_OPTIONS='' node dist/local/issueToken.js)" && ACCESS_TOKEN="$NEXT_ACCESS_TOKEN"
プロフィールを作成し、成功レスポンスを受け取った場合にのみ、返された UUID を取得します。リクエストが失敗した場合は、次の手順に進まないでください。409 は、そのメールアドレスがすでに存在することを示します。コミット済みかもしれない POST をむやみに再試行せず、別のメールアドレスを使うか、既存のプロフィールを取得してください。
CREATED="$(curl -fsS -X POST "$BASE_URL/api/v1/users" \
-H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
-d '{"name":"John Doe","email":"john@example.com"}')" &&
NEXT_PROFILE_ID="$(printf '%s' "$CREATED" | NODE_OPTIONS='' node --input-type=module -e '
import { z } from "zod"
let text = ""
for await (const chunk of process.stdin) text += chunk
const { data } = z.object({ data: z.object({ id: z.string().uuid() }) }).parse(JSON.parse(text))
console.log(data.id)
')" && PROFILE_ID="$NEXT_PROFILE_ID" && printf '%s\n' "$CREATED"
レスポンスは {"data":{"id":"…","name":"John Doe","email":"john@example.com","createdAt":"…"}} で、HTTP 201 と、新しいプロフィールの Location ヘッダーを伴います。プロフィールとページ分割された一覧を取得します。
curl -fsS "$BASE_URL/api/v1/users/$PROFILE_ID" \
-H "Authorization: Bearer $ACCESS_TOKEN" &&
curl -fsS "$BASE_URL/api/v1/users?limit=20&offset=0" \
-H "Authorization: Bearer $ACCESS_TOKEN"
名前を更新します。PATCH はボディを返さないため、-i でステータスとヘッダーを表示します。
curl -fsS -i -X PATCH "$BASE_URL/api/v1/users/$PROFILE_ID" \
-H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
-d '{"name":"John Smith"}'
HTTP 204 が返ることを確認します。最初のターミナルで Ctrl+C を押し、前述の起動ブロックを再実行してください。PostgreSQL は稼働させたままにします。二つ目のターミナルで次の GET を再実行します。同じ UUID、更新後の名前、メールアドレス、作成日時が残っているはずです。
curl -fsS "$BASE_URL/api/v1/users/$PROFILE_ID" \
-H "Authorization: Bearer $ACCESS_TOKEN"
そのプロフィールを削除し、その後の 404 レスポンスを確認します。最後のコマンドでは、エラー JSON を読めるよう、意図的に -f を省略しています。
curl -fsS -i -X DELETE "$BASE_URL/api/v1/users/$PROFILE_ID" \
-H "Authorization: Bearer $ACCESS_TOKEN" &&
curl -sS -i "$BASE_URL/api/v1/users/$PROFILE_ID" \
-H "Authorization: Bearer $ACCESS_TOKEN"
DELETE は、ボディが空の 204 を返します。続く GET は、error と requestId を含む 404 を返します。各レスポンスには新しい X-Request-ID があり、エラーボディの ID はヘッダーの ID と一致します。認証はボディの解析より前に実行され、JSON パーサーはデコード後のリクエストボディを 10 KiB に制限します。
API ドキュメント
OpenAPI でこの API を記述する際は、以下の結果を使用します。
| リクエスト | ステータス |
|---|---|
| 有効なプロフィールの作成 | 201、Location 付き |
| プロフィールまたはページ分割された一覧の取得 | 200 |
| 既存プロフィールの更新または削除 | 204、空のボディ |
| トークンの欠落、期限切れ、署名の不正、発行者または対象者の不一致 | 401 |
| 有効なトークンにルートの必須スコープがない | 403 |
| 無効な UUID、フィールド、ページ指定、または不正な JSON | 400 |
| 前後の空白除去と小文字化後のメールアドレスの重複 | 409 |
| 10 KiB を超える JSON ボディ | 413 |
| 不明または削除済みプロフィールの UUID | 404 |
プロフィールの書き込みでは、name と email のみを受け付けます。PATCH には少なくとも一方が必要です。ページ分割はデフォルトで 20 件、最大 100 件で、オフセットはゼロから 10,000 の範囲です。二つのスコープを、すべてのプロフィールに対する管理者権限として記述し、Bearer トークン方式とリクエスト ID ヘッダーもドキュメントに含めてください。
デプロイ時の考慮事項
実際のユーザーが利用するアプリケーションでは、ローカル署名ツールを、ID プロバイダーの管理者用アクセストークンフローに置き換えてください。信頼できる設定を通じて公開鍵を取得し、対応する発行者と対象者をサーバーに設定します。このサンプルは固定の検証鍵を使用し、鍵のローテーションやトークンの失効は実装していません。
リモートアクセスには HTTPS を使用し、使い捨てのスーパーユーザー用データベースを、権限を制限したアプリケーション用認証情報を使うものに置き換えてください。また、スキーマ同期ではなくマイグレーションを使用します。Node プロセスを停止しても PostgreSQL は停止しません。作業が終わったら API を停止し、作成したデータベースコンテナだけを削除して、一時データを破棄してください。
docker rm --force --volumes "$DB_CONTAINER"
まとめ
これらのプロフィールに後からファイル添付が必要になった場合は、Transloadit のアップロード APIが、独立した取り込み・処理サービスを提供します。
