Downloads

Download API Gateway Integration Examples for ColdFusion

by Aaron Longnion
8 min read

Introduction
The “API Gateway Integration Examples for ColdFusion” Download is a curated set of practical, production-ready samples showing how to connect Adobe ColdFusion or Lucee (CFML) applications to an API Gateway, with a focus on AWS API Gateway HTTP/REST APIs. It includes ColdFusion handlers, mapping templates, CORS rules, Security patterns, and Deployment guides. Whether you’re modernizing a CFML app behind an API gateway, exposing REST endpoints, or standardizing service integrations, these examples help you move from trial-and-error to a proven, repeatable setup—fast.

Contents show

Overview

This resource is a downloadable ZIP that provides end-to-end examples for integrating a ColdFusion backend with an API gateway. It covers HTTP proxy Integration, VPC Link configurations for private services, request/response mapping, Authentication (JWT/OAuth2/Cognito), CORS, and caching strategies. You’ll find code that works on both Adobe ColdFusion and Lucee, plus IaC samples (OpenAPI, Terraform) to help you deploy consistently.

The examples are organized for clarity, with separate folders for core patterns (simple proxy, Lambda proxy emulation, CORS), Authentication guards, and observability. Each example is annotated with instructions and “why it matters” commentary, so you can adapt it to your environment quickly.

What You’ll Get

  • PDF quick-start guide (18 pages): A concise walkthrough of the concepts, Architecture options, and step-by-step Configuration.
  • CFML code examples:
    • /cfml/handlers/:
      • api.cfm (simple JSON response)
      • proxyHandler.cfm (HTTP proxy style, x-forwarded-* awareness)
      • corsPreflight.cfm (OPTIONS method handling)
    • /cfml/components/:
      • ApiUtils.cfc (request parsing, JSON helpers, CORS helpers)
      • Jwt.cfc (HS256/RS256 JWT validation, including Cognito token examples)
  • API Gateway artifacts:
    • /apigw/openapi.yaml (OpenAPI 3.0 spec for import)
    • /apigw/mappings/ (request/response mapping templates for REST API)
    • /apigw/cors-policy.json (reusable CORS config)
  • Infrastructure as Code:
    • /iac/terraform/ (HTTP API with custom domain + stage + routes)
    • /iac/cloudformation/ (REST API stack with VPC Link option)
  • Postman collection:
    • /postman/ColdFusion-API-Gateway.postman_collection.json
  • Environment examples:
    • /env/.env.sample
    • /env/cfadmin-setup-instructions.md (notes for Adobe CF 2021/2023, Lucee 5.x)
  • Deployment and operations:
    • /ops/nginx-proxy.conf (optional Reverse proxy in front of CF)
    • /ops/logging.md (request IDs, correlation, and CloudWatch logs mapping)
    • /ops/waf-rules.md (WAF/IP allowlist examples)
  • Licensing and changelog:
    • LICENSE, CHANGELOG.md
See also  Download the ColdFusion Performance Tuning Guide (PDF)

Supported Environments and Requirements

  • ColdFusion engines:
    • Adobe ColdFusion 2018/2021/2023
    • Lucee 5.3+ (recommended 5.4+)
  • API Gateways:
    • AWS API Gateway HTTP API (preferred for cost/latency)
    • AWS API Gateway REST API (for mapping template Features and advanced policies)
  • Networking:
    • Public HTTP integration, or private integration using VPC Link to ALB/NLB
  • Tooling:
    • Git, cURL/Postman, and optional Terraform/CloudFormation
  • System requirements:
    • Java 11+ for newer CF engines
    • HTTPS certificate if using custom domain names on API Gateway
    • Outbound internet or private link for logs/monitoring

Installation and Setup

Download and Unpack

  1. Download the ZIP file named apigw-coldfusion-examples.zip from your release source or repository.
  2. Extract into your project directory, e.g., /var/www/apigw-examples or C:\web\apigw-examples.
  3. Ensure your ColdFusion webroot maps to the /cfml folder for testing or create an alias/virtual directory.

Configure ColdFusion

  1. Web server connector (optional but recommended):
    • Configure IIS/Apache/Nginx to proxy to ColdFusion’s AJP/HTTP connector.
    • Use the provided /ops/nginx-proxy.conf as a reference if using Nginx.
  2. Datasource and Security:
    • If sample code touches a DB, create a datasource in CF Admin and name it DS_API (or adjust in code).
    • Disable directory browsing and ensure .cfc direct invocation is restricted as needed.
  3. CORS and headers:
    • Confirm that ColdFusion is permitted to set custom headers (e.g., Access-Control-Allow-Origin).
    • Ensure response compression is enabled in your web server for JSON payloads.

Configure AWS API Gateway (HTTP API recommended)

Step 1: Import the OpenAPI spec

  • Console: API Gateway > Create API > Import > Upload /apigw/openapi.yaml.
  • Verify routes map to your intended paths (e.g., /v1/orders, /v1/health).

Step 2: Set up integrations

  • Integration target: Your CF endpoint (public URL or private ALB via VPC Link).
  • For HTTP API:
  • For REST API:
    • Use /apigw/mappings/ templates to pass through body, query params, and headers if not using proxy.

Step 3: Enable CORS and security

  • Configure CORS on API Gateway: Allow methods OPTIONS, GET, POST, PUT, DELETE; headers Content-Type, Authorization, X-Request-Id.
  • Use JWT authorizer (Cognito or third-party) or Lambda Authorizer as needed.
  • Optionally add AWS WAF to your API’s custom domain for IP allowlists/rate-based rules.
See also  Download ColdFusion Email Templates (Password Reset & Verify Email)

Step 4: Deploy and test

  • Create a stage: dev or v1.
  • Assign a custom domain if required; upload or reference an ACM certificate.
  • Test with Postman using the provided collection.

How to Use the Examples

Quick Start: Simple JSON Handler

  • File: /cfml/handlers/api.cfm
  • Purpose: Shows minimal REST response with proper headers and JSON encoding.
    Example:


response = { status=”ok”, time=now(), message=”Hello from ColdFusion via API Gateway” };
cfheader(name=”Content-Type”, value=”application/json; charset=utf-8″);
cfheader(name=”Cache-Control”, value=”no-store”);
writeOutput( serializeJSON(response) );

  • Map API Gateway route /v1/hello to this handler.

CORS Preflight

  • File: /cfml/handlers/corsPreflight.cfm
  • Handles OPTIONS requests to satisfy browser preflight.
  • Ensure API Gateway has CORS enabled; ColdFusion sets:
    • Access-Control-Allow-Origin: *
    • Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
    • Access-Control-Allow-Headers: Content-Type, Authorization

Proxy-aware Handler

  • File: /cfml/handlers/proxyHandler.cfm
  • Reads forwarded headers to capture client IP and protocol.


clientIp = cgi.HTTP_X_FORWARDED_FOR ?: cgi.REMOTE_ADDR;
proto = cgi.HTTP_X_FORWARDED_PROTO ?: “http”;
cfheader(name=”X-App-Client-IP”, value=clientIp);
writeOutput( serializeJSON({ ip=clientIp, proto=proto, path=cgi.SCRIPT_NAME, qs=cgi.QUERY_STRING }) );

JWT Verification with Cognito

  • File: /cfml/components/Jwt.cfc
  • Validates tokens (RS256) against JWKS.
  • Map your secured routes to check Authorization header, then:


jwt = createObject(“component”, “components.Jwt”);
claims = jwt.verify(authHeader=getHttpRequestData().headers[“Authorization”], jwksUrl=application.jwksUrl, audience=”your-aud”, issuer=”https://cognito-idp.region.amazonaws.com/yourPoolId”);
if (!claims.valid) {
cfheader(statuscode=401, statustext=”Unauthorized”);
abort;
}

Observability

  • Propagate request IDs:
    • Read x-amzn-RequestId or x-request-id from headers.
    • Log them with each request for traceability.
  • Use /ops/logging.md for CloudWatch log filters and correlation tips.

Best practices

Security

  • Prefer JWT authorizers or OAuth2 with Cognito/third-party IdP; avoid passing raw session cookies through API Gateway.
  • Validate CORS carefully; use allowlists instead of wildcard origins for production.
  • Sanitize inputs; return consistent error JSON with no stack traces exposed.
  • Apply AWS WAF rules and rate limits; consider per-consumer API keys if needed.

Performance

  • Enable API Gateway caching (REST APIs) for GET endpoints with stable responses.
  • Use gzip/brotli compression at the edge (CloudFront) or web server.
  • Keep ColdFusion responses small and structured; avoid unnecessary serialization of large nested objects.
  • For private services, use VPC Link to ALB/NLB to reduce public exposure and improve latency.

Reliability and Observability

  • Implement health endpoints (/v1/health) returning lightweight JSON.
  • Add request timeout guards on both sides (Gateway and CFML).
  • Log request IDs and principal/user claims; integrate with CloudWatch or ELK/OpenSearch.

Maintainability

  • Store routes and targets in OpenAPI; import to API Gateway to avoid drift.
  • Use Terraform or CloudFormation for consistent deployments across environments.
  • Keep mapping templates versioned; document transformations explicitly.

Benefits and Use Cases

  • Faster Onboarding: Pre-built CFML handlers, OpenAPI specs, and IaC templates reduce setup time from days to hours.
  • Cleaner separation: An API gateway fronting ColdFusion provides routing, throttling, CORS, and auth outside the app code.
  • Security uplift: Centralized JWT/OAuth2, WAF, and Rate limiting keep legacy CFML endpoints safer.
  • Modernization path: Wrap existing CFM/CFC endpoints with a standardized REST interface, enabling mobile/web clients and Microservices to consume them.
  • Observability: Consistent request IDs and log patterns streamline Troubleshooting and SLO monitoring.
See also  Download ColdFusion PDF Generation Examples (CFDOCUMENT)

Common scenarios:

  • Migrating legacy CFMs into a RESTful interface.
  • Exposing Lucee services to front-end SPAs with proper CORS and caching.
  • Adding API keys and usage plans without Refactoring code.
  • Integrating with ALB via VPC Link to keep ColdFusion private.

Keywords naturally covered: AWS API Gateway integration, CFML REST, Adobe ColdFusion, Lucee Server, OpenAPI/Swagger import, request/response mapping templates, VPC Link, CORS Configuration, JWT authorizer, Cognito, custom domain, CloudFront, WAF.

Key Takeaways

  • This download gives you working ColdFusion + API Gateway examples: handlers, mapping templates, OpenAPI specs, and IaC.
  • You can choose between HTTP API (lean, fast) and REST API (advanced mappings, caching).
  • Security, CORS, and logging are baked in, with JWT validation and traceable request IDs.
  • Use the OpenAPI file to bootstrap routes and the Terraform/CloudFormation samples to automate deployments.
  • Adaptable to both Adobe ColdFusion and Lucee, with clear guidance and tested patterns.

FAQ

How do I switch from HTTP API to REST API without rewriting my ColdFusion code?

Use the provided OpenAPI and mapping templates under /apigw/mappings/ for REST API. Keep your ColdFusion handlers identical; only adjust the API Gateway integration type and mappings. The request and response structures will remain consistent if you use the supplied templates.

Can I run this behind a private network using VPC Link?

Yes. Point your API Gateway integration to an internal ALB/NLB via VPC Link. The examples include CloudFormation/Terraform snippets and guidance on headers like X-Forwarded-For/Proto so your ColdFusion app can infer correct scheme and client IP.

Does this work with both Adobe ColdFusion and Lucee?

Yes. All CFML samples are engine-agnostic, tested on Adobe CF 2021/2023 and Lucee 5.x. Any engine-specific notes are included in /env/cfadmin-setup-instructions.md.

How should I handle CORS for a single-page application?

Enable CORS in API Gateway for the specific origins your SPA uses, allow necessary headers (Authorization, Content-Type), and ensure OPTIONS is routed. The provided corsPreflight.cfm demonstrates server-side headers to complement Gateway CORS.

Can I import the OpenAPI file directly into API Gateway?

Yes. Use /apigw/openapi.yaml. After import, review routes, integrations, and authorizers. Then deploy to a stage and test with the Postman collection provided.

About the author

Aaron Longnion

Aaron Longnion

Hey there! I'm Aaron Longnion — an Internet technologist, web software engineer, and ColdFusion expert with more than 24 years of experience. Over the years, I've had the privilege of working with some of the most exciting and fast-growing companies out there, including lynda.com, HomeAway, landsofamerica.com (CoStar Group), and Adobe.com.

I'm a full-stack developer at heart, but what really drives me is designing and building internet architectures that are highly scalable, cost-effective, and fault-tolerant — solutions built to handle rapid growth and stay ahead of the curve.

View all posts

You may also like