A well-designed local REST API lab lets you explore ideas safely, inspect behavior up close, and iterate quickly. You can test requests, validate assumptions, and rehearse operational steps without risking production systems. This guide provides a practical, end-to-end setup using Node.js and Express, with a small but realistic API, observable verification steps, and clear failure and recovery guidance. The goal is to create a narrow, measurable pilot that runs entirely on your workstation, binds only to loopback, and exposes a few endpoints that are easy to probe with curl. You will verify success with concrete checks, handle common failures, and close with a repeatable checklist you can run every time you sit down to experiment. ## Version and Environment Inventory Establish your runtime and topology upfront so you can reproduce results and avoid drift. Keep the first pilot simple: single host, local loopback, non-privileged ports, in-memory storage, and request logging. ### Topology - Single workstation, no external network calls. - API binds to 127.0.0.1:3000. - Optional mock-stub routes within the same process for external dependencies. - In-memory data to avoid persistence complexity during the first pass. ### Prerequisites and Version Checks Use tools you probably already have. Target a maintained LTS runtime and confirm versions.

Component	Example Version	How to Check	Notes
Node.js	18.x LTS or 20.x LTS	`node -v`	Use LTS for stability
npm	9.x+ (bundled with Node)	`npm -v`	Ensures modern package behavior
curl	7.68+	`curl --version`	For quick HTTP tests
Git (optional)	2.30+	`git --version`	For easy rollback
MongoDB (optional)	6.x	`mongod --version`	Only if you add persistence later

## Safe Configuration Path Choose defaults that are safe, local, and reversible. - Scope: Start with an in-memory store and a few endpoints (health, items CRUD, a stubbed external interaction). This limits moving parts while still providing real operational value. - Binding: Listen on 127.0.0.1 (loopback) and a non-privileged port (3000). This avoids exposing the lab to your LAN or requiring admin rights. - Environment: Keep configuration in a local .env file that is not committed to shared repos. Use simple, obvious keys like PORT and BIND_ADDRESS . - Validation and Logging: Validate inputs to surface errors early and log requests at development verbosity to make behavior observable. - Reversibility: Keep all files in a dedicated directory. If something breaks, you can delete the folder and recreate it in minutes. ## Implementation: Build the Local Lab API This implementation uses Node.js with Express, dotenv for configuration, morgan for dev logging, and joi for input validation. ### 1) Create the Project # Create and enter a clean workspace directory mkdir rest-api-lab && cd rest-api-lab # Confirm Node and npm node -v npm -v # Initialize the project and install dependencies npm init -y npm install express dotenv morgan joi ### 2) Add Configuration Create a .env file in the project root: # .env PORT=3000 BIND_ADDRESS=127.0.0.1 NODE_ENV=development ### 3) Implement the API Create server.js with a minimal but realistic REST API. // server.js require('dotenv').config(); const express = require('express'); const morgan = require('morgan'); const Joi = require('joi'); const { randomUUID } = require('crypto'); const app = express(); app.use(express.json()); app.use(morgan('dev')); // Config const PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : 3000; const BIND_ADDRESS = process.env.BIND_ADDRESS || '127.0.0.1'; // In-memory data store const items = []; // Validation schema const itemSchema = Joi.object({ name: Joi.string().min(1).max(100).required(), price: Joi.number().min(0).precision(2).required() }); // Health endpoint app.get('/health', (req, res) => { res.status(200).json({ status: 'ok', uptime_s: process.uptime(), version: '1.0.0' }); }); // List items app.get('/items', (req, res) => { res.json({ count: items.length, items }); }); // Create item app.post('/items', (req, res, next) => { const { error, value } = itemSchema.validate(req.body); if (error) return res.status(400).json({ error: error.details[0].message }); const item = { id: randomUUID(), ...value, createdAt: new Date().toISOString() }; items.push(item); res.status(201).json(item); }); // Read item app.get('/items/:id', (req, res) => { const item = items.find(i => i.id === req.params.id); if (!item) return res.status(404).json({ error: 'Not found' }); res.json(item); }); // Update item (full or partial) app.put('/items/:id', (req, res) => { const idx = items.findIndex(i => i.id === req.params.id); if (idx === -1) return res.status(404).json({ error: 'Not found' }); // Validate if fields exist const schema = Joi.object({ name: Joi.string().min(1).max(100).optional(), price: Joi.number().min(0).precision(2).optional() }).min(1); const { error, value } = schema.validate(req.body); if (error) return res.status(400).json({ error: error.details[0].message }); items[idx] = { ...items[idx], ...value, updatedAt: new Date().toISOString() }; res.json(items[idx]); }); // Delete item app.delete('/items/:id', (req, res) => { const idx = items.findIndex(i => i.id === req.params.id); if (idx === -1) return res.status(404).json({ error: 'Not found' }); const [removed] = items.splice(idx, 1); res.status(200).json({ deleted: removed.id }); }); // Simulated external call (constructed example) app.post('/payments/charge', (req, res) => { const schema = Joi.object({ amount: Joi.number().integer().min(1).required(), currency: Joi.string().length(3).uppercase().required(), source: Joi.string().required() }); const { error, value } = schema.validate(req.body); if (error) return res.status(400).json({ error: error.details[0].message }); // Simulate success without calling external services res.status(200).json({ id: 'ch_' + randomUUID().replace(/-/g, '').slice(0, 24), status: 'succeeded', amount: value.amount, currency: value.currency, created: Math.floor(Date.now() / 1000) }); }); // Not found handler app.use((req, res) => { res.status(404).json({ error: 'Route not found' }); }); // Error handler app.use((err, req, res, next) => { console.error(err); res.status(500).json({ error: 'Internal server error' }); }); app.listen(PORT, BIND_ADDRESS, () => { console.log(`REST API lab listening on http://${BIND_ADDRESS}:${PORT}`); }); ### 4) Start the Server node server.js Expected console output: REST API lab listening on http://127.0.0.1:3000 ## Practical Examples: Requests and Workflows Use curl to exercise the API. These examples show both the command and an example response so you can compare your results. ### Health Check curl -i http://127.0.0.1:3000/health Expected response: HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 {"status":"ok","uptime_s":1.234,"version":"1.0.0"} ### Create an Item curl -i -X POST http://127.0.0.1:3000/items \ -H 'Content-Type: application/json' \ -d '{"name":"pencil","price":0.99}' Expected response: HTTP/1.1 201 Created Content-Type: application/json; charset=utf-8 {"id":"8b2...","name":"pencil","price":0.99,"createdAt":"2024-01-01T00:00:00.000Z"} ### List Items curl -i http://127.0.0.1:3000/items Expected response: HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 {"count":1,"items":[{"id":"8b2...","name":"pencil","price":0.99,"createdAt":"2024-01-01T00:00:00.000Z"}]} ### Read an Item ITEM_ID= curl -i http://127.0.0.1:3000/items/$ITEM_ID Expected: 200 with the JSON item. ### Update an Item curl -i -X PUT http://127.0.0.1:3000/items/$ITEM_ID \ -H 'Content-Type: application/json' \ -d '{"price":1.25}' Expected: 200 with updated fields and updatedAt . ### Delete an Item curl -i -X DELETE http://127.0.0.1:3000/items/$ITEM_ID Expected: 200 with {"deleted":""} . ### Simulated Payment Charge curl -i -X POST http://127.0.0.1:3000/payments/charge \ -H 'Content-Type: application/json' \ -d '{"amount":500,"currency":"USD","source":"tok_visa"}' Expected: 200 with a JSON object containing id , status , amount , currency , created . ### Endpoint Map A quick reference to what you set up:

Method	Endpoint	Purpose	Success Code
GET	/health	Process health and version	200
GET	/items	List all items	200
POST	/items	Create an item	201
GET	/items/:id	Read an item by id	200
PUT	/items/:id	Update an item	200
DELETE	/items/:id	Delete an item	200
POST	/payments/charge	Stub external charge call	200

## Verification and Diagnostics Verification is about observable facts: running process, open port, expected responses, and clean logs. ### 1) Process and Port - On macOS/Linux: ss -lntp | grep :3000 || lsof -iTCP:3000 -sTCP:LISTEN - On Windows PowerShell: netstat -ano | findstr :3000 Expected: A listener on 127.0.0.1:3000 tied to your Node process. ### 2) Endpoint Behavior - Happy path: /health returns 200 with status ok; /items returns 200 with a count; POST /items returns 201 and a new id. - Error handling: POST /items with missing name or price should return 400 and a helpful error message; /items/:id with an unknown id returns 404. ### 3) Logs The morgan dev logger should print one line per request with method, path, status code, and response time. Unexpected 500s or long response times are signals to investigate. ### 4) Configuration Sanity - Ensure .env is loaded: temporarily set PORT=3001 in .env , restart, and verify the server logs show 3001. - Confirm loopback binding: server should report http://127.0.0.1:PORT , not 0.0.0.0 . ## Failure Modes and Recovery Here are common issues and how to resolve them.

Symptom	Probable Cause	Fix	Verify
EADDRINUSE on startup	Port 3000 in use	Change PORT in .env or stop the other process	ss/lsof or netstat shows only your node listener
Cannot GET /health	Wrong port or host	Check URL and PORT/BIND_ADDRESS; restart server	curl returns 200 with status ok
400 on POST /items	Invalid input	Send both name and price, correct JSON	201 Created with new id
404 on /items/:id	Unknown id	Use the id returned by POST or re-create	GET returns 200 for that id
500 errors	Code or validation bug	Check server logs; add console.error in error handler	Subsequent calls return expected 2xx/4xx
Module not found	Packages missing	`npm install` to restore dependencies	Server starts without error
Wrong Node features	Node version drift	Use LTS; reinstall or switch version	`node -v` shows target LTS

### Rollback and Recovery Procedures - Quick reset: Stop the server (Ctrl+C), delete the rest-api-lab directory, and recreate from the steps in this guide. - Dependency restore: Remove node_modules and package-lock.json , then run npm install . - Config restore: Revert .env to the simple baseline ( PORT=3000 , BIND_ADDRESS=127.0.0.1 , NODE_ENV=development ). - Code restore: If you used Git, git checkout -- . to discard local changes since last commit. - Port conflict workaround: Temporarily set PORT=0 in server.js to auto-assign a free port, then read the console for the selected port and revert later to the fixed port. ## Operations Checklist Use this short checklist to run your lab consistently.

Step	Action
1	Confirm Node and npm versions (`node -v`, `npm -v`)
2	Ensure a clean working directory and simple `.env`
3	Install dependencies (`npm install`)
4	Start the server (`node server.js`)
5	Verify port binding (`ss/lsof` on macOS/Linux, `netstat` on Windows)
6	Run basic checks: `/health`, `/items` (empty), create-read-update-delete cycle
7	Exercise the stubbed `/payments/charge` endpoint
8	Inspect logs for status codes and timings
9	Capture notes on behavior and any anomalies
10	Stop the server (Ctrl+C) and reset environment if needed

## Conclusion You now have a safe, observable local REST API lab that runs on loopback, uses non-privileged ports, and implements a small but realistic set of endpoints. The implementation choices favor simplicity, reversibility, and clear diagnostics. With this foundation you can extend carefully: - Add persistence: introduce a local database only when needed, starting with a single collection or table and clear migration steps. - Add authentication: begin with a simple token check in a middleware, then expand to more robust controls as required. - Add external integrations: keep them stubbed locally until you have strong tests and guardrails, then enable controlled calls in a separate, clearly marked environment. Most importantly, keep each change measurable and easy to inspect locally. That discipline reduces rework, improves confidence, and helps teams move faster with fewer surprises.