Building REST APIs with CFML

What is a REST API, and why does it matter?

A REST API (Representational State Transfer) is a way for two systems to talk to each other over HTTP. Instead of returning an HTML page, the server returns structured data — almost always JSON — that a client (a browser, a mobile app, another server) can consume programmatically.

Why does this matter for ColdFusion developers?

• Modern frontends (React, Vue, plain JavaScript) don't load full pages — they fetch JSON and update the UI
• Mobile apps need data, not markup
• Microservices and integrations call each other via HTTP APIs
• ColdFusion sits naturally in this model: it already handles HTTP requests, runs queries, and can serialise any struct or array to JSON with a single function call

In this lesson you will work with a fully functional REST API that is already deployed in your environment. The goal is to understand how it's built, explore it with curl, and internalise the patterns you'll use in your own projects.

Three layers in every CFML REST request: the client sends HTTP, ColdFusion processes and queries, the H2 database returns rows — serialised back as JSON.

What's already running in your lab

Three files are pre-deployed on the ColdFusion server:

All three files are baked into the lab image — nothing to create or install.

To open the API console, right-click the ColdFusion tab in the lab panel and open it in a new browser tab, then navigate to /api-test.cfm.

api-test.cfm — a browser-based console showing all four endpoints. Click any card to expand it and send a live request.

1. The simplest JSON endpoint

A ColdFusion REST endpoint is just a .cfm file that:

1. Sets the Content-Type header to application/json
2. Writes serialised data to the response and exits

<!--- /api/tickets.cfm (GET — list all tickets) --->
<cfscript>
  cfheader(name="Content-Type", value="application/json");
  cfheader(name="Access-Control-Allow-Origin", value="*");

  q = queryExecute(
    "SELECT t.id, t.title, t.status, t.priority, t.created_at, u.name AS submitter
     FROM   hd_tickets t
     JOIN   hd_users   u ON u.id = t.user_id
     ORDER  BY t.created_at DESC",
    {}, { datasource: "training_db" }
  );

  writeOutput(serializeJSON({ "total": q.recordCount, "tickets": queryToArray(q) }));
</cfscript>

No framework, no routing config, no annotations. Just headers, a query, and serializeJSON.

2. Reading URL parameters safely

Always use val() or explicit type checks before using URL values in queries. Never concatenate URL params directly into SQL.

<cfscript>
  id = structKeyExists(url, "id") ? val(url.id) : 0;
  if (id LTE 0) {
    cfheader(statuscode="400", statustext="Bad Request");
    writeOutput(serializeJSON({ "error": "id must be a positive integer" }));
    abort;
  }

  q = queryExecute(
    "SELECT id, title, status, priority, description FROM hd_tickets WHERE id = :id",
    { id: { value: id, cfsqltype: "cf_sql_integer" } },
    { datasource: "training_db" }
  );

  if (q.recordCount == 0) {
    cfheader(statuscode="404", statustext="Not Found");
    writeOutput(serializeJSON({ "error": "Ticket not found" }));
    abort;
  }

  writeOutput(serializeJSON(queryToArray(q)[1]));
</cfscript>

The :id named binding in queryExecute is a cfqueryparam equivalent — it escapes the value and prevents SQL injection.

3. Accepting a JSON POST body

POST requests carry their payload in the request body, not the URL. ColdFusion exposes it via getHttpRequestData().content:

<cfscript>
  rawBody = toString(getHttpRequestData().content);

  if (!isJSON(rawBody)) {
    cfheader(statuscode="400", statustext="Bad Request");
    writeOutput(serializeJSON({ "error": "Request body must be valid JSON" }));
    abort;
  }

  data = deserializeJSON(rawBody);

  if (!structKeyExists(data, "title") || !len(trim(data.title))) {
    cfheader(statuscode="400", statustext="Bad Request");
    writeOutput(serializeJSON({ "error": "title is required" }));
    abort;
  }

  queryExecute(
    "INSERT INTO hd_tickets (title, description, status, priority, user_id, created_at)
     VALUES (:title, :desc, 'open', :priority, :user_id, CURRENT_TIMESTAMP)",
    {
      title:    { value: left(trim(data.title), 255), cfsqltype: "cf_sql_varchar" },
      desc:     { value: data.description ?: "",       cfsqltype: "cf_sql_varchar" },
      priority: { value: data.priority    ?: "medium", cfsqltype: "cf_sql_varchar" },
      user_id:  { value: data.user_id     ?: 1,        cfsqltype: "cf_sql_integer" }
    },
    { datasource: "training_db" }
  );

  cfheader(statuscode="201", statustext="Created");
  writeOutput(serializeJSON({ "created": true }));
</cfscript>

4. Routing on HTTP method

Route on cgi.REQUEST_METHOD to handle GET, POST, and DELETE in a single .cfm file.

ColdFusion exposes the HTTP verb via cgi.REQUEST_METHOD. A single file can handle all methods:

<cfscript>
  cfheader(name="Content-Type", value="application/json");
  method = cgi.REQUEST_METHOD;

  if (method == "GET")    { /* list or fetch */ }
  if (method == "POST")   { /* create */        }
  if (method == "DELETE") { /* close ticket */  }

  cfheader(statuscode="405", statustext="Method Not Allowed");
  writeOutput(serializeJSON({ "error": "Method not allowed" }));
  abort;
</cfscript>

5. CFC Service pattern

Large APIs benefit from separating the HTTP layer (request/response handling) from the data layer (queries and business logic). TicketService.cfc is already deployed and provides a clean interface:

<cfscript>
  svc     = createObject("component", "TicketService");
  tickets = svc.getAll();           // array of structs
  ticket  = svc.getById(1);         // struct + comments array
  newId   = svc.create("My ticket", "Details here", 1, "high");
  svc.close(newId);
</cfscript>

The endpoint file stays thin — it validates input, calls the service, and writes the response. The service holds all the SQL. This separation makes both easier to test and maintain.

Seed the Help Desk database

Before hitting the API, make sure the Help Desk schema is populated. Open the ColdFusion 2025 browser tab and click the DB Test button.

Click the DB Test button to open the seed utility.

1. Click Run Seed Script

Click Run Seed Script to create and populate the Help Desk schema.

2. A confirmation screen confirms the seed completed successfully

All four tables created and sample rows inserted — the database is ready.

Or seed from the terminal if you prefer:

curl -s http://localhost:8500/seed-db.cfm

If the data is already present it skips all inserts and tells you — safe to run multiple times.

Activity 1 — Explore the live API

The endpoint is already running. Use curl to inspect it:

# List all tickets
curl -s http://localhost:8500/api/tickets.cfm | python3 -m json.tool

# Confirm Content-Type header
curl -s -I http://localhost:8500/api/tickets.cfm | grep -i content-type

You should see a JSON response with a total count and a tickets array. The Content-Type header must be application/json.

Activity 2 — Fetch a single ticket

Add the ?id= parameter to fetch one specific ticket:

# Fetch ticket #1
curl -s "http://localhost:8500/api/tickets.cfm?id=1" | python3 -m json.tool

# Test a 404 — ticket 999 does not exist
curl -s -w "\nHTTP %{http_code}\n" "http://localhost:8500/api/tickets.cfm?id=999"

The first command should return a single ticket object with a title field. The second should return HTTP 404 and {"error":"Ticket not found"}.

Activity 3 — Create a ticket via POST

Send a JSON body to create a new ticket:

curl -s -X POST http://localhost:8500/api/tickets.cfm \
  -H "Content-Type: application/json" \
  -d '{"title":"Monitor flickering","description":"Display flickers on login","priority":"high","user_id":3}' \
  | python3 -m json.tool

A successful response returns HTTP 201 and {"created": true}. Verify the ticket was actually saved by listing again:

curl -s http://localhost:8500/api/tickets.cfm | python3 -m json.tool | grep -A3 "Monitor flickering"

Key takeaways

When all the checks above are green, this lesson is complete. Your progress is saved automatically — move straight on to the next lesson.