HTTP & Web

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();
  }
}

1	Get a `WebClient` attached to the current Vert.x instance.
2	HTTP GET request for path `/` to host `icanhazdadjoke.com`, on port `443` (HTTPS).
3	Do not forget to enable SSL encryption.
4	Explicitly say that we want JSON data.
5	The response will automatically be converted to JSON.
6	We expect an HTTP 200 status code, else it will fail the response.
7	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.