Introduction
This downloadable resource is a production‑ready ColdFusion/CFML starter project for building a JSON REST API quickly and reliably. It provides a clean Architecture, sensible defaults, and batteries‑included Features such as routing, Authentication, validation, Error handling, logging, caching, and documentation. Whether you use Adobe ColdFusion or Lucee, this JSON API boilerplate helps you ship faster, maintain consistency across services, and follow Best practices without reinventing the wheel.
What You’ll Get
- Complete CFML project scaffold suitable for Adobe ColdFusion and Lucee
- CommandBox powered dev environment (server.json, box.json) for 1‑command startup
- Application.cfc preconfigured for API mode (no views, secure defaults, RESTful settings)
- Routing with ColdBox or a lightweight routes.cfm (choose your flavor)
- Modular endpoints (e.g., /v1/health, /v1/auth, /v1/users) with handlers and services
- Standardized JSON response wrapper and error middleware
- Authentication using JWT (login, refresh, revoke) with role/permission hooks
- Input validation helpers (schemas and reusable validators)
- CORS middleware with configurable origins, methods, and headers
- Database ready:
- ORM or query services (choose either), datasource config, and example models
- Migration scripts using cfmigrations (optional)
- Seed data for local development
- Caching setup (in‑memory/Tiered) with examples for response and query caching
- Logging via LogBox (file and console appenders) and request correlation IDs
- Environment Configuration via .env files (dotenv) and secrets placeholders
- API documentation with Swagger/OpenAPI (Swagger.json + Swagger UI)
- Postman collection and environment for quick testing
- Test suite with TestBox (unit, Integration, and handler tests)
- CI pipeline example (GitHub Actions) for linting and tests
- Dockerfile and docker-compose.yml for containerized runs
- README with diagrams, Architecture notes, and common tasks
Optional Download links (choose one):
- ZIP: https://example.com/cf-json-api-starter.zip
- Git: git clone https://example.com/cf-json-api-starter.git
Overview
This starter accelerates building a ColdFusion REST API that returns clean JSON while enforcing consistent status codes, pagination, Security headers, and traceable logs. It’s ideal for greenfield services, Refactoring legacy CFML code into Microservices, or creating a reference architecture for a larger engineering team.
Key design goals:
- Minimal boilerplate to create new endpoints
- Clear separation of concerns (handlers/controllers, services, models)
- Safe defaults (CORS, Rate limiting hooks, input validation)
- Observability (structured logs, request IDs, health and readiness checks)
- Cross‑platform support (Windows, macOS, Linux) and both major CF engines
Supported Environments
- CF Engines:
- Adobe ColdFusion 2021+ (recommended: latest update)
- Lucee 5.3+ (recommended: latest stable)
- OS: Windows, macOS, Linux
- Java: 11+ (match your engine’s guidance)
- Local server runner: CommandBox (required for quick start)
- Optional: Docker and Docker Compose
Quick Start: Installation and Setup
Prerequisites
- Install Java 11 or 17 (ensure java -version works)
- Install CommandBox: https://www.ortussolutions.com/products/commandbox
- Optional: Docker Desktop if you prefer containers
- Database server (e.g., PostgreSQL, MySQL, or MSSQL) if using persistence
Download
- Clone or download the ZIP.
- Open a terminal in the project folder.
Configure Environment
- Copy .env.example to .env
- Set required keys (examples):
- APP_ENV=development
- APP_SECRET=change-this-in-prod
- JWT_SECRET=another-strong-secret
- DATASOURCE_NAME=apiDSN
- DB_HOST=localhost
- DB_USER=apiuser
- DB_PASSWORD=apipass
- Define the datasource in your engine or via Application.cfc env parsing (the scaffold includes an example resolver).
Start the Server
- Run: box install
- Start: box start
- The server will boot using server.json defaults. The console prints the local URL (e.g., http://127.0.0.1:57234).
Verify Health
- GET /v1/health
- Expect JSON: { “status”:”ok”, “uptime”:…, “version”:”…” }
Optional: Database Migrations
- Configure your datasource (admin or Application.cfc)
- Run migrations: box task run migrations:up
- Seed data: box task run seeds:load
Configuration Guide
Routing
- ColdBox: routes.cfm defines routes like /v1/users -> users handler
- Lightweight mode: a simple router maps methods and paths to CFC functions
- Add routes and handlers under /api/handlers and /api/routes
Authentication (JWT)
- POST /v1/auth/login returns a JWT on valid credentials
- Use Authorization: Bearer
on protected routes - Token lifetime and refresh cycle configurable in /config/jwt.cfc
- Example roles: admin, user; add custom claims in authService.cfc
Database and ORM
- Choose ORM (Hibernate) or query-driven services
- Models in /api/models; services in /api/services
- Example repository pattern and transactions included
- Use parameterized queries or entitySave for safety and Performance
CORS and Security headers
- Configure origins, methods, and headers in /config/cors.cfc
- Includes secure defaults: X-Content-Type-Options, X-Frame-Options, etc.
- Rate limiting hook available via interceptor (enable as needed)
Logging and Monitoring
- LogBox configured for console + file logs with JSON layout option
- Request correlation IDs added to each log entry
- Health, readiness, and metrics endpoints available (/v1/health, /v1/metrics if enabled)
OpenAPI/Swagger
- Swagger JSON generated at /swagger.json
- Swagger UI served at /docs (can be disabled in production)
- Update endpoint annotations or OpenAPI config to reflect changes
How to Use the API
Create a User (example)
- POST /v1/users
- Body:
{
“email”: “user@example.com”,
“password”: “StrongP@ssw0rd”,
“name”: “API User”
} - Response: 201 Created with user object (sans password)
Log In
- POST /v1/auth/login
- Body:
{
“email”:”user@example.com”,
“password”:”StrongP@ssw0rd”
} - Response: 200 OK with jwt and refreshToken
Access a Protected Route
- GET /v1/users/me
- Header: Authorization: Bearer
- Response: 200 OK with current user profile
Curl Quick Checks
- Health: curl -s http://localhost:port/v1/health
- Login:
curl -X POST http://localhost:port/v1/auth/login \
-H “Content-Type: application/json” \
-d ‘{“email”:”user@example.com”,”password”:”StrongP@ssw0rd”}’ - Protected:
curl http://localhost:port/v1/users/me -H “Authorization: Bearer TOKEN”
Best practices
Security Hardening
- Always set strong, rotated secrets for APP_SECRET and JWT_SECRET
- Enforce HTTPS (terminate TLS at proxy or enable in container)
- Validate and sanitize all inputs; never trust request payloads
- Use parameterized queries or ORM; avoid string concatenation
- Scope tokens with roles/permissions; minimize token lifetime
- Disable Swagger UI in production or protect with auth
Performance and Reliability
- Cache frequent GET responses and heavy queries
- Use pagination consistently (limit, offset) and sensible limits
- Prefer serializeJSON with proper date/time formatting (ISO‑8601)
- Compress responses (GZIP/Brotli) at proxy or server
- Add circuit breakers/timeouts for external dependencies
Testing and CI/CD
- Write TestBox unit tests for services; handler tests for endpoints
- Run tests locally: box testbox run
- Use the provided GitHub Actions pipeline as a baseline
- Lint and format CFML for consistency (adopt a style guide)
Deployment Tips
- Use Docker for immutable deployments
- Externalize configuration via environment variables
- Include health/readiness endpoints in your orchestrator (Kubernetes, ECS)
- Forward request IDs through proxies and log them end‑to‑end
Benefits and Use Cases
- Faster time‑to‑market: Start with a working CFML REST API and focus on Business logic, not setup
- Consistency: Shared response format, Error handling, and logging across services
- Security by default: JWT auth, CORS, and headers are preconfigured with safe defaults
- Flexibility: Works on both Adobe ColdFusion and Lucee, on Windows/macOS/Linux or Docker
- Observability: Built‑in health checks, request IDs, and structured logs simplify support
- Ideal for:
- Greenfield ColdFusion JSON API projects
- Converting legacy CFML pages into APIs
- Internal Microservices and BFF layers
- Prototyping clients with Swagger and Postman
Related terms: CFML API starter, ColdBox REST template, Lucee API scaffold, Adobe ColdFusion Web services, OpenAPI for ColdFusion, JWT in CFML, CommandBox server.
Key Takeaways
- This starter is a complete JSON API boilerplate for ColdFusion/Lucee with routing, auth, validation, logging, and docs.
- CommandBox enables a one‑command Local server, with .env configuration for quick customization.
- Security, performance, and testing are treated as first‑class concerns.
- Use Swagger and Postman to explore and collaborate; wire in CI/CD and Docker for production.
FAQ
How do I switch between Lucee and Adobe ColdFusion?
Update server.json to the desired engine. For example, set cfengine to lucee@5.3 or adobe@2021. Then run box start. The codebase is engine‑agnostic, but confirm datasource and ORM settings for each engine.
Can I use this without a database?
Yes. You can skip ORM/migrations and use in‑memory stores or external services. The services layer isolates persistence, so you can replace repositories with stubs or external API clients.
How do I add a new endpoint?
Create a handler (e.g., /api/handlers/orders.cfc) with functions for GET/POST/etc., then add routes in routes.cfm (or ColdBox routes). Implement input validation and return the standardized response structure.
Is Docker supported?
A Dockerfile and docker-compose.yml are included. Build with docker build -t cf-api . and run via Docker Compose up. Provide environment variables via compose or your orchestrator’s secrets manager.
How do I enable rate limiting?
Enable the provided interceptor/middleware, set thresholds in /config/security.cfc, and optionally back it with an external store (Redis) for distributed limits. You can also add per‑route policies.
