cfhttp

The previous lesson read an Authorization header sent to your own endpoint. This one sends the request in the first place: cfhttp is how ColdFusion calls another server over HTTP, whether that's a third-party REST API, another internal service, or just fetching a remote file.

Learning Objectives

After completing this lesson, you'll be able to:

• Make a basic GET request with cfhttp and read the response.
• Send query parameters, headers, and a JSON body with cfhttpparam.
• Read the cfhttp result structure: statusCode, fileContent, responseHeader, and more.
• Download a binary file (like an image) with getAsBinary.
• Know the real, documented default for throwOnError, and why setting it explicitly matters.

How cfhttp Fits Together

A Basic GET Request

<cfhttp url="https://api.example.com/users" method="GET" result="apiResult" timeout="10">
    <cfhttpparam type="header" name="Accept" value="application/json">
</cfhttp>

<cfif apiResult.statusCode CONTAINS "200">
    <cfset users = deserializeJSON(apiResult.fileContent)>
</cfif>

cfhttp(url = "https://api.example.com/users", method = "GET", result = "apiResult", timeout = 10) {
    cfhttpparam(type = "header", name = "Accept", value = "application/json");
}

if (apiResult.statusCode contains "200") {
    users = deserializeJSON(apiResult.fileContent);
}

The cfhttp Result Structure

Sending Data With cfhttpparam

A single cfhttp tag can carry several cfhttpparam children, each one attaching a different piece of the outgoing request, distinguished by its type attribute.

A Real Example: POST With a JSON Body and Auth Header

This is the client side of the exact pattern the previous lesson protected on the server side: an Authorization header, checked on arrival there, attached here before the request ever leaves.

payload = { "name": "New Product", "price": 29.99 };

cfhttp(url = "https://api.example.com/products", method = "POST", result = "apiResult", timeout = 10) {
    cfhttpparam(type = "header", name = "Authorization", value = "Bearer " & application.apiToken);
    cfhttpparam(type = "header", name = "Content-Type", value = "application/json");
    cfhttpparam(type = "body", value = serializeJSON(payload));
}

if (apiResult.statusCode contains "201") {
    created = deserializeJSON(apiResult.fileContent);
}

Downloading a File

getAsBinary controls whether the response is treated as text or raw bytes, essential for anything that isn't plain text, like an image or a PDF.

<cfhttp url="https://example.com/logo.png" method="GET" getAsBinary="yes" result="imgResult">
</cfhttp>

<cffile action="write" file="#expandPath('./downloaded-logo.png')#" output="#imgResult.fileContent#">

A Real Discrepancy: throwOnError's Actual Default

Worth flagging directly: cfdocs.org's community reference currently lists throwOnError's default as true, but Adobe's own official documentation and Lucee's own official documentation both state the default is false, neither engine throws an exception on an HTTP error status by default, it's left in the result struct's statusCode and errorDetail instead.

Common Beginner Mistakes

Best Practices

• Set result to a descriptive variable name, not the cfhttp default, especially with more than one cfhttp call on a page.
• Set throwOnError explicitly rather than relying on the default, and check the documented behavior differs depending on which source you read.
• Always set a timeout when calling an external service.
• Set Content-Type explicitly (via cfhttpparam type="header") whenever sending a body, don't assume the receiving API will guess correctly.

Interview Questions

Summary

In this lesson, you made GET and POST requests with cfhttp, attached query parameters, headers, and a JSON body with cfhttpparam, read the result structure's statusCode and fileContent, downloaded a binary file with getAsBinary, and covered a real, verified discrepancy in how throwOnError's default is documented across sources.

What's Next?

The next lesson covers cfldap: connecting to an LDAP directory server (like Active Directory) to query, add, modify, or delete directory entries, commonly used for centralized authentication against a company's existing user directory.