CFML makes it really easy to interact with any HTTP/S endpoint via the cfhttp tag/construct (https://cfdocs.org/cfhttp). The cfhttp call will generate an HTTP/S request and parse the response into a nice CFML structure.

cfhttp( url="https://www.google.com/", result="result" ){
    cfhttpparam( name="q", type="formfield", value="cfml" )
}
writeDump( result )

As you can see from the example above, you can pass parameters to the HTTP request by using the child cfhttpparam construct. This parameter can be of many different types: header, body, xml, cgi, file, url, formfield, cookie depending on the requirements of the http endpoint.

The Result Structure

The result structure will contain the following keys:

CFHTTP Arguments

This construct accepts many arguments with different features you can use when executing http/s calls, below we list just the most common ones, you can find them all here: https://cfdocs.org/cfhttp​

Basically, you can do any type of http/s calls and consume any type of RESTFul webservices with a nice CFML syntax!

CFHTTPParam

As mentioned before in our example we can use the cfhttpparam construct to pass parameters to the http/s endpoint. The parameters can be of different types as we can see in the following table.

cfhttpParam( type="", name="", value="", file="", encoded="", mimetype="" );

Param Types

Param Arguments

The available param arguments to the cfhttpparam construct are:

Here is another example for you:

cfhttp( url="https://myrestapp.com/user", result="local.result", method="post" ){
        cfhttpparam( name="x-api-token", type="header", value="123" )
        cfhttpparam( 
                type="body", 
                value=serializeJson( '{
                        name : "luis",
                         age : 2
                }' )
        )
}
writeDump( result )

Hyper : HTTP Builder

Leveraging cfhttp is very very easy to use. However, it can be cumbersome and not necessarily fluent or object oriented. For this, we have provided a module called Hyper which can help you build fluent and amazing HTTP Builders (https://forgebox.io/view/hyper)

Hyper was built after coding several API SDK's for various platforms — S3SDK, cbstripe, and cbgithub, to name a few. I noticed that I spent a lot of time setting up the plumbing for the requests and a wrapper around cfhttp. Each implementation was mostly the same but slightly different. It was additionally frustrating because I really only needed to tweak a few values, usually just the Authorization header. It would be nice to create an HTTP client pre-configured for each of these SDK's. It seemed the perfect fit for a module.

The problem it solves

Hyper exists to provide a fluent builder experience for HTTP requests and responses. It also provides a powerful way to create clients, Bulider objects with pre-configured defaults like a base URL or certain headers.

HyperBuilder

The component you will most likely inject is the HyperBuilder. This is commonly aliased as hyper.

component {
    property name="hyper" inject="HyperBuilder@Hyper";
}

The HyperBuilder creates new requests. This can be done in one of two ways:

1. Calling the new method will create a new request with the configured defaults.

2. Calling any method on HyperRequest on the HyperBuilder instance will create a new request and forward on the method call.

Using the HyperBuilder lets you easily create requests with defaults while also avoiding having to deal with providers directly.

HyperRequest

Though the HyperBuilder is the component you will most likely inject, HyperRequest is the component will you interact with the most. HyperRequest provides a fluent interface to configure your HTTP call.

Example:

hyper.get( "https//api.github.com/users" );
​
hyper.setMethod( "PUT" )
    .withHeaders( { "Authorization" = "Bearer #token#" } )
    .setUrl( "https://jsonplaceholder.typicode.com/posts/1" )
    .setBody( {
        title: "New Title"
    } )
    .send();

Request Defaults

Hyper allows you to configure defaults for your requests. This is particularly useful for reducing boilerplate in your application.

Defaults are set on the HyperBuilder instance. The easiest way to do this is to configure it in WireBox:

// config/WireBox.cfc
component {
​
    function configure() {
        map( "StarWarsClient" )
            .to( "hyper.models.HyperBuilder" )
            .asSingleton()
            .initWith(
                baseUrl = "https://swapi.co/api"
            );
    }
​
}

Now, you can inject this pre-configured builder wherever you need in your application:

component {
​
    property name="StarWarsClient" inject="id";
​
    function findUser( id ) {
        return StarWarsClient.get( "/people/#id#" );
    }
​
}

You can even create multiple clients using this approach:

// config/WireBox.cfc
component {
​
    function configure() {
        map( "SWAPIClient" )
            .to( "hyper.models.HyperBuilder" )
            .asSingleton()
            .initWith(
                baseUrl = "https://swapi.co/api"
            );
​
        map( "GitHubClient" )
            .to( "hyper.models.HyperBuilder" )
            .asSingleton()
            .initWith(
                baseUrl = "https://api.github.com",
                headers = {
                    "Authorization" = getSetting( "SWAPI_TOKEN" )
                }
            );
    }
​
}

You can also set or change the defaults by either passing the key / value pairs in to the init method or by calling the appropriate HyperRequest method on the HyperBuilder.defaults property.

var hyper = new Hyper.models.HyperBuilder(
    baseUrl = "https://api.github.com"
);
hyper.defaults.withHeaders( { "Authorization" = token } );