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.

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.

Hyper runs on Adobe ColdFusion 11+ and Lucee 5+.

ColdBox is not required, but mappings are provided for ColdBox users automatically.

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.

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();

Execute a GET request.

Execute a POST request.

Execute a PUT request.

Execute a PATCH request.

Execute a DELETE request.

Send the HTTP request and return a HyperResponse.

Gets the base URL for the request.

Sets the base URL for the request.

Gets the URL for the request.

Sets the URL for the request.

Sets the resolveURL parameter for the request.

Gets the HTTP method for the request.

Sets the HTTP method for the request.

Sets the username and password for HTTP Basic Auth.

Gets the username for the request.

Sets the username for the request.

Gets the password for the request.

Sets the password for the request.

Gets the timeout for the request.

Sets the timeout for the request.

A convenience method to not follow any redirects.

Gets the maximum number of redirects to follow.

Sets the maximum number of redirects to follow. A value of * will follow redirects infinitely.

Gets the body for the request.

Sets the body for the request. Complex values will be serialized before sending the request.

Gets the body format for the request.

Sets the body format for the request.

A convenience method to set the body format and Content-Type to json.

A convenience method to set the body format and Content-Type to form fields.

Gets the referrer for the request, if any.

Gets the headers for the request.

Sets the headers for the request.

Set a header for the request.

Add additional headers to the request.

Check if the request has a header with the given name.

A convenience method to set the Content-Type header.

A convenience method to set the Accept header.

Gets the query parameters for the request.

Sets the query parameters for the request.

Set a query parameter for the request.

Add additional query parameters to the request.

Check if the request has a query parameter with the given name.

Sets the throw on error property for the request. If true, error codes and status will be turned in to exceptions.

A convenience method to throw on errors.

A convenience method to not throw on errors.

Quickly set many request properties using a struct. The key should be the name of one of the properties on the request, e.g. url, headers, method, body.

The HyperResponse component is a read-only wrapper to easily grab different information about the response.

Gets the status code for the response.

Gets the data for the response.

Gets the HyperRequest instance associated with this response.

Gets the charset value for the response.

Gets the timestamp for when this response was recieved.

Returns the data of the request as deserialized JSON.

Returns true if the request status code is considered successful.

Returns true if the request status code is considered a redirect.

Returns true if the request status code is considered either a client error or a server error.

Returns true if the request status code is considered a client error.

Returns true if the request status code is considered a server error.

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 } );