Introduction

The Gradle HTTP Plugin provides a straight-forward means of configuring and executing HTTP requests from your Gradle build, using the HttpBuilder-NG client library.

Getting Started

In order to use the HTTP Plugin to create HTTP tasks, you first need to apply it to your build. The plugin is available via the common Gradle plugins repository as io.github.http-builder-ng.http-plugin. You can then apply it to your build with by adding the following to your build.gradle file:

build.gradle
plugins {
  id "io.github.http-builder-ng.http-plugin" version "0.1.1"
}

Next, you will need to create a task of type io.github.httpbuilderng.http.HttpTask to preform your requests. The following is an example:

build.gradle
task notify(type:HttpTask){
    config {
        request.uri = 'http://something.com'
    }
    post {
        request.uri.path = '/notify'
        request.body = [event: 'activated']
        response.success {
            println 'The event notification was successful'
        }
    }
}

This notify task will send a POST request to http://something.com/notify with the given payload whenever the task is executed.

Configuration

The HTTP Plugin is a thin Gradle configuration layer on top of the HttpBuilder-NG library, which means that most of the configuration delegates to classes defined in that project. You will want to familiarize yourself with the HttpBuilder configuration objects.

http Extension

The plugin provides an http extension block used to configure the global default client configuration and the client library to be used.

The library property accepts either an instance of the HttpLibrary enum (CORE, APACHE, or OKHTTP) or the case-insensitive string version of the enum name to configure which underlying HTTP client library is used to make the requests. The CORE library is used by default if not explicitly specified.

The config(Closure) and config(Consumer<HttpObjectConfig>) methods accept a Closure or Consumer<HttpObjectConfig> which will be passed into the HttpBuilder::configure method if no specific configuration is applied in the task itself (via the config method on the task).

The documentation for the HttpObjectConfig configuration interface is available in either the JavaDocs or User Guide for the HttpBuilder-NG project.

An example configuration would be similar to the following:

http {
    library = 'apache'
    config {
        request.uri = 'http://localhost:1234'
    }
}

HttpTask

The primary purpose of this plugin is to allow the simple creation of Gradle tasks to make HTTP requests. This is done by creating a task of type io.github.httpbuilderng.http.HttpTask and providing the desired configuration, such as:

task hook(type:HttpTask){
    config {
        request.uri = 'http://localhost:9876'
        request.body = [id:42]
    }
    post {
        request.uri.path = '/build-hook'
        response.success {
            lifecycle.info 'The external build hook was executed.'
        }
    }
}

which would submit a POST to the http://localhost:9876/build-hook URL whenever the task is executed.

There are six supported HTTP request methods: GET, HEAD, POST, PUT, DELETE, and PATCH. The OPTIONS and TRACE methods are intentionally omitted since they do not seem useful in this context (if you find them useful, please submit an issue to add support for them). The request method DSL is based directly on the HttpConfig interface from the HttpBuilder-NG library and there is a configuration block in the task DSL for each supported method type. All configuration is provided as either a Groovy Closure or a Consumer<HttpConfig>. Lastly, each request method has an asynchronous version denoted by the request method name suffixed by Async (e.g. postAsync) similar to the interface provided by HttpBuilder.

Each task can make one or more HTTP requests. Additional requests are configured and executed sequentially (unless async). An example of the above configuration with multiple requests would be:

task hook(type:HttpTask){
    config {
        request.uri = 'http://localhost:9876'
        request.body = [id:42]
    }
    post {
        request.uri.path = '/build-hook'
        response.success {
            lifecycle.info 'The external build hook was executed.'
        }
    }
    post {
        request.uri.path = '/notify'
        response.success {
            lifecyclt.info 'Notification sent.'
        }
    }
}

The response values of the requests are not used or stored. If any interaction on response values is desired, the HttpBuilder response handlers must be used to perform the desired actions.

Tip
 See the More About Tasks section of the Gradle User Guide for more information about creating tasks.

License

The Gradle HTTP Plugin is licensed under the Apache 2 open source license.

Copyright 2017 HttpBuilder-NG Project

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.