Document Handling

cfhttp

Content Author

Tim Cunningham

timcunningham71

cfhttp makes HTTP calls from your ColdFusion server to an internet address of your choice. It is important to remember that it is the ColdFusion server that will be calling the URL, not the browser that is calling your ColdFusion page. Think of cfhttp as if you have proxy browser on your server that can send and receive information to any address on the internet. Imagine that this "virtual browser" on the server can save the information that it receives to a variable, so that it can be manipulated or passed to the user who has called your ColdFusion page.

Making a HTTP call

There are many attributes that the cfhttp tag can take. The simplest cfhttp call can be done like this:

<cfhttp url="http://cfmumbojumbo.com" method="get" />

This is equivalent to you getting on the server, starting the browser of your choice and putting http://cfmumbojumbo.com in the address bar. All the information returned from that HTTP request has been put into a variable called cfhttp. If you dump the cfhttp variable like this:

<cfhttp url="http://cfmumbojumbo.com" method="get" />
<cfdump var="#cfhttp#" />

You can see all the information about the raw html return (fileContent) as well as the mime type, the header information, and status codes. The response body, called filecontent by ColdFusion, contains (in this case) all the raw HTML from the page. If you had pointed the URL to a JPG or image file, it would return a java byte array.

Commonly Used Attributes

As of CF 2018, there are 30 attributes you can use with cfhttp. For this chapter, we will cover the most commonly used ones:

  • Method defines the HTTP method (sometimes referred to as "verbs") of action to be performed on the URL. The methods that cfhttp understands are GET, POST, HEAD, PUT, DELETE, and OPTIONS. The most commonly used verbs are GET and POST. GET retrieves whatever information returns from the URL. POST can submit data to the chosen URL (form fields, uploaded files, etc.) and then return the resultant page. OPTIONS will return with information explaining what verbs the web server will accept from you. HEAD is another verb; it responds the same as a GET, but only returns the meta-information that is in the returning page's header. It will not return the response body (HTML, image, file body, etc.). PUT can upload file on the remote server. DELETE can remove a file on the requested URL. The web server on the URL must be set up for PUT and DELETE.

-URL is the address to which you want to talk. It can be an IP address, hostname, or fully qualified domain name. If you pass URL parameters in the url, they will be included in your request. For example, url="http://www.myserver.com?id=5&myname=Tim" will be passed to the remote server just as if it were typed into a web browser. You can include http:// or https://; if you do not, cfhttp will default to http://. If you include a port number in the URL, it will override the port attribute. For example, url="http://www.myserver.com:8088" will connect on port 8088. Remember, the ColdFusion server is going to need permissions to talk to the remote server on port 8088, otherwise you may get unexpected results.

-File and Path is used if you want the response body to be written to a file; use this attribute and give it a file name and path:

<cfhttp url="cfmumbojumbo.com" path="C:/test" file="test.html" />
<!--- Will take the HTML from the web page and write it to C:/test/test.html on your ColdFusion server. --->
  • GetAsBinary tries to convert the response to binary. This can be set to Auto, Never, No, or Yes. Auto will convert the response to binary if it is recognized as proper form binary data; otherwise it will converted to text. Never will treat all returned data as test, regardless of its true MIME type. GetAsBinary is useful when you are using cfhttp to grab images, zip files, or other binary data off other web sites.
<cfhttp url="http://6e33d2c506c5fcafb083-2091e9475e9ec26fdd926321647b46b0.r56.cf1.rackcdn.com/tim-bennadel.png" />

  • UserName and Password is used when the web page is protected by basic authentication on the web server. Note: these attributes are not useful for a typical web site designed login screen.

  • Result is the name of the variable you want to hold returned results.

  • Port is the port number you wish to make the HTTP request through. The server that your ColdFusion code is running on must have permissions to communicate on this port. The default is port 80.

  • Timeout is the value in seconds that the ColdFusion server will wait for a successful response before it considers the request to have failed.