Skip to main content
Version: Current

Core concepts and set-up

Before diving into the core concepts, let's start with how to set up the Genesis HTTP Client in your project.

Installation​

The Genesis HTTP Client is included in the Genesis Platform from version 8.1 onwards. To use it, add the following dependency to your module's build.gradle.kts file:

dependencies {
    implementation("global.genesis:genesis-http-client")
}

GenesisHttpClient​

The GenesisHttpClient is the main class you interact with. It provides methods for making HTTP requests.

val client = GenesisHttpClient()

You can configure the client as a constructor parameter, passing a Ktor HttpClient object if needed.

Request methods​

The client supports all standard HTTP methods:

  • GET: client.get<T>()
  • POST: client.post<T>()
  • PUT: client.put<T>()
  • DELETE: client.delete<T>()

Each method returns a TypedHttpResponse<T> object, where T is the expected response body type.

Configuring requests​

You can configure requests using a DSL within a lambda function. Common configuration options include:

  • url: the endpoint URL
  • header: HTTP headers
  • query: query parameters
  • body: request body (for POST, PUT)

Example:

    eventHandler<Account>("API_TRADE_INSERT") {
        onCommit {
            httpClient
                .post<Account> {
                    url = "http://localhost:8080/account"
                    header("Authorization", "Basic ABCDEFG")
                }
        }
    }

Response handling​

The HttpResponse<T> object contains:

  • statusCode: the HTTP status code
  • headers: response headers
  • data: the response body, deserialised to type T

Example:

    eventHandler("API_TRADE_INSERT") {
        onCommit { event ->
            client.get<String>(
                path = "http://localhost:8080/trades",
                request = event.details) {
                header("Authorization", "Basic ABCDEFG")
                query("tradeId", event.details)
            }.data
            ack()
    }
}

In the next sections, we'll explore more advanced features and usage patterns to help you make the most of the Genesis HTTP Client.