Performing HTTP requests to other services

This document will show you how to perform HTTP requests to other services.

What you will build

You will build a Vert.x application that use the API at https://icanhazdadjoke.com/api and displays a new joke every 3 seconds:

The application fits in a single JokeVerticle class.

What you need

A text editor or IDE
Java 11 or higher
Maven or Gradle

Create a project

The code of this project contains Maven and Gradle build files that are functionally equivalent.

Using Maven

Here is the content of the pom.xml file you should be using:

Maven pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

  <modelVersion>4.0.0</modelVersion>

  <groupId>io.vertx.howtos</groupId>
  <artifactId>http-client-howto</artifactId>
  <version>1.0-SNAPSHOT</version>

  <properties>
    <vertx.version>5.0.0.CR2</vertx.version>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>io.vertx</groupId>
        <artifactId>vertx-stack-depchain</artifactId>
        <version>${vertx.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

  <dependencies>
    <dependency>
      <groupId>io.vertx</groupId>
      <artifactId>vertx-core</artifactId>
    </dependency>
    <dependency>
      <groupId>io.vertx</groupId>
      <artifactId>vertx-web-client</artifactId>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.13.0</version>
        <configuration>
          <release>11</release>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>exec-maven-plugin</artifactId>
        <version>3.5.0</version>
        <configuration>
          <mainClass>io.vertx.howtos.httpclient.JokeVerticle</mainClass>
        </configuration>
      </plugin>
    </plugins>
  </build>

</project>

Using Gradle

Assuming you use Gradle with the Kotlin DSL, here is what your build.gradle.kts file should look like:

Gradle build.gradle.kts

plugins {
  java
  application
}

repositories {
  mavenCentral()
}

dependencies {
  val vertxVersion = "5.0.0.CR2"
  implementation("io.vertx:vertx-core:${vertxVersion}")
  implementation("io.vertx:vertx-web-client:${vertxVersion}")
}

application {
  mainClass = "io.vertx.howtos.httpclient.JokeVerticle"
}

Getting jokes with the Vert.x web client

The Vert.x web client greatly simplifies making HTTP requests compared to the more low-level API found in the Vert.x core API. It does The WebClient class can be found in the io.vertx:vertx-web-client artifact.

To get new jokes, we need to make HTTP GET requests to https://icanhazdadjoke.com/api. To do that every 3 seconds, we will simply use a Vert.x periodic timer.

The API returns simple JSON objects. We can test it using a command-line tool like curl:

$ curl -H "Accept: application/json" https://icanhazdadjoke.com/
{"id":"IJBAsrrzPmb","joke":"What do you call a cow with two legs? Lean beef.","status":200}

Here is the code of the JokeVerticle class:

package io.vertx.howtos.httpclient;

import io.vertx.core.AbstractVerticle;
import io.vertx.core.Vertx;
import io.vertx.core.http.HttpResponseExpectation;
import io.vertx.core.json.JsonObject;
import io.vertx.ext.web.client.HttpRequest;
import io.vertx.ext.web.client.WebClient;
import io.vertx.ext.web.codec.BodyCodec;

public class JokeVerticle extends AbstractVerticle {

  private HttpRequest<JsonObject> request;

  @Override
  public void start() {

    request = WebClient.create(vertx) // (1)
      .get(443, "icanhazdadjoke.com", "/") // (2)
      .ssl(true)  // (3)
      .putHeader("Accept", "application/json")  // (4)
      .as(BodyCodec.jsonObject()); // (5)

    vertx.setPeriodic(3000, id -> fetchJoke());
  }

  private void fetchJoke() {
    request.send()
      .expecting(HttpResponseExpectation.SC_OK)  // (6)
      .onSuccess(result -> {
        System.out.println(result.body().getString("joke")); // (7)
        System.out.println("🤣");
        System.out.println();
      })
      .onFailure(e -> System.out.println("No joke fetched: " + e.getMessage()));
  }

  public static void main(String[] args) {
    Vertx vertx = Vertx.vertx();
    vertx.deployVerticle(new JokeVerticle()).await();
  }
}

Get a WebClient attached to the current Vert.x instance.
HTTP GET request for path / to host icanhazdadjoke.com, on port 443 (HTTPS).
Do not forget to enable SSL encryption.
Explicitly say that we want JSON data.
The response will automatically be converted to JSON.
We expect an HTTP 200 status code, else it will fail the response.
The body is a JSON object, and we write the result to the console.

Running the application

The JokeVerticle already has a main method, so it can be used as-is to:

create a Vertx context, then
deploy JokeVerticle.

You can run the application from:

your IDE, by running the main method from the JokeVerticle class, or
with Maven: mvn compile exec:java, or
with Gradle: ./gradlew run (Linux, macOS) or gradle run (Windows).

Summary

This document covered:

the Vert.x web client for making HTTP requests,
extracting data from a JSON response,
Vert.x periodic tasks.