Poet configuration

The HttpPoet poet is backed by an OkHttpClient. You can provide one to one of the HttpPoet constructors.

most of the fields presented here can be configured at the poet level, meaning that this configuration will be applied for all requests, or at the method call level as named parameters, meaning that the configuration will only be applied at this specific method call. Method calls configurations override poet configuration (only for the given call).

Base url

The base url can be an url or an empty string, but it CANNOT be null. If it is an empty string, every request you make will have to provide a full URL, not just a path. In general, every url or endpoint referenced in requests will be appended to the base url.

Default headers

You can set default headers, headers that will be used in all requests (except if overridden) like in the following example

poet.headers["Content-Encoding"] = "UTF-8"
poet.removeHeader("Content-Encoding")

// override encoding for this specific call
poet.get("/api/something", headers: ["Content-Encoding": "UTF-16"])

Content Type

You can set the content type used by default for request bodies like in the following example

poet.contentType = ContentType.XML

or set it for a specific call

poet.post('/foos', contentType: ContentType.XML, body: [bar: 'bar'])

Error response handler

You can customize the default error response handler, used when retrieving directly an object content. By default, it will throw a ErrorResponseException if the response wasn't successful

poet.errorResponseHandler = { Response r -> 
  println(r.code())
  return null
}
// or for a specific call
poet.post('/foos', errorResponseHandler: myHandler)

On Pre/Post Execute

This library provides onPreExecute(Request) and onPostExecute(Request, Response) closure that will be called respectively just before the request is executed and just before the response is handled. By default these are null but it can be useful to set them, for example for logging purposes

poet.onPreExecute = {
  println "Will perform request $it"
}

poet.onPostExecute = { Request request, Response response ->
  println "Will handle response $response"
}

poet.get("/wiki/Groovy_(langage)")

poet.get('/bars', onPreExecute: customHandler1, onPostExecute: customHandler2)

Composers

Composers are used to transform any kind of data into an actual request body You can learn more aboout composers here.

Parsers

Parsers are used to transform the response body into data you want to manipulate You can learn more about parsers here.

Customize OkHttp client

If you want to customize the underlying OkHttpClient, you can pass your own intance in one of the HttpPoet's constructor, or you can access it with the okHttpClient property