HTTP Connector

HTTP connector

A built-in HTTP connector facilitates making HTTP calls directly from the DSL.

It is possible to reference and use context attributes in a connector definition.
The common use-cases include URL and body generation, authentication headers, etc.

An HTTP connector response is automatically converted into a context attribute based on the content type.
There is a built-in support for JSON and XML content types.

Default behaviour of the connector is that it retries request only on following response status codes: 408, 425, 429, 500, 502, 503, 504.
It is possible to add or remove status code from retry list using retryableError and unretryableError options. See examples below.

GET requests

Making an HTTP GET is as simple as providing a request url

http {
    url 'https://request-url'
}

An url can be generated using Groovy GString and context attributes.

An example below queries GitHub repositories using a keyword attribute.

http {
  url "https://api.github.com/search/repositories?q=topic:${keyword}"
}

POST requests

HTTP POST request has the method set to POST.

JSON body

The request body is set using the payload expression result. The payload expression can reference and use available context attributes.
Retryable error forces connector to try again even on 404 NOT_FOUND response from server. This can be useful in subsequent call to easily poll for object until it is ready.

http {
  url "${middleware.url}/api/v1/client"
  method 'POST'
  body """whatever"""
  retryableError 404  
}

A JSON request body is specified using jsonBody together with application/json content type.

http {
    url 'http://localhost'
    method 'POST'
    jsonBody firstname: client.firstname, lastname: client.lastname
}

JSON body with Base64-encoded files

It is possible to specify a JSON request body using descriptors. The corresponding files are encoded using Base64.

http {
    url 'http://localhost'
    method 'POST'
    jsonBody id: [front: base64(upload.idFront), back: base64(upload.idBack)]
}

HTTP body with binary data

Some API endpoints require sending binary data in HTTP body. This is supported by rawBody.
You can send content of a file by passing a file descriptor to it. If the parameter is a string, it's send as it is,
maps and lists are rendered as json.

http {
    url 'http://localhost'
    method 'POST'
    rawBody upload.idFront
}

Form data

The formData specifies an HTTP request using a form data using application/x-www-form-urlencoded content type.

http {
    url 'http://localhost'
    method 'POST'
    formData 'data1', content1
    formData 'data2', content2
}

Multipart data

It is possible to generate a request body as multipart data using file descriptors.

http {
    url 'http://localhost'
    method 'POST'
    multipart 'file', upload.idFront
}

Optionally, it is possible to use a JSON builder, see JsonBuilder

http {
    url 'http://localhost'
    method 'POST'
    jsonBody {
      client {
        firstName client.firstname
        lastName client.lastname
      }
    }
}

JWT in body

The request body is specified using jwtBody. The payload expression can reference and use available context attributes.
In addition to payload it necessary to define secret which is a shared secret with the other service.
alg is optional and defaults to HS256. Possible values are "HS256", "HS384" and "HS512"".

http {
  url "${thirdparty.url}/webhook"
  method 'POST'
  jwtBody {
      payload """whatever"""
      secret "secret"
      alg "HS512"
  }
}

JWT body with Base64-encoded files

It is possible to specify a JWT request body using descriptors. The corresponding files are encoded using Base64.

http {
    url 'http://localhost'
    method 'POST'
    jwtBody {
        payload([front: base64(upload.idFront), back: base64(upload.idBack)])
        secret "secret"
    }
}

Request method

The method specifies an HTTP request method. If omitted, the default method is GET.

The method can be one of the following:

DELETE
GET
HEAD
OPTIONS
PATCH
POST
PUT
TRACE

http {
    url "/api/files/cache/${uuid}"
    method 'DELETE'
}

Request headers

The header specifies an HTTP request header.

http {
    url 'http://localhost'
    header 'X-Auth', authtoken
    method 'POST'
    body payload
}

Content type

The contentType specifies an HTTP request Content-Type header.

http {
    url 'http://localhost'
    contentType 'APPLICATION_JSON_VALUE'
    method 'POST'
    body payload
}

Authorization

Basic authentication

The basicAuth specifies an HTTP basic authentication credentials.

http {
    url 'http://localhost'
    basicAuth 'user', 'password'
}

Bearer authentication

The bearerAuth specifies a Bearer Authentication token used in Authentication HTTP header. unretryableError makes
connector not to retry the request on specified response status code which might become handy if there's non-standard server/gateway behaviour.

http {
    url "${api.url}/verify" 
    bearerAuth access_token
    unretryableError 500
}