Creating a hypermedia-driven RESTful web service

duration 30 minutes

Prerequisites:

You’ll explore how to use Hypermedia As The Engine Of Application State (HATEOAS) to drive your RESTful web service on Open Liberty.

What you’ll learn

You will learn how to use hypermedia to create a specific style of a response JSON, which has contents that you can use to navigate your REST service. You’ll build on top of a simple inventory REST service that you can develop with MicroProfile technologies. You can find the service at the following URL:

http://localhost:9080/inventory/hosts

The service responds with a JSON file that contains an array of registered hosts. Each host has a collection of HATEOAS links:

[
  {
    "hostname": "foo",
    "_links": [
      {
        "href": "http://localhost:9080/inventory/hosts/foo",
        "rel": "self"
      }
    ]
  },
  {
    "hostname": "bar",
    "_links": [
      {
        "href": "http://localhost:9080/inventory/hosts/bar",
        "rel": "self"
      }
    ]
  },
  {
  "hostname": "*",
  "_links": [
    {
      "href": "http://localhost:9080/inventory/hosts/*",
      "rel": "self"
    }
  ]
  }
]

What is HATEOAS?

HATEOAS is a constrained form of REST application architecture. With HATEOAS, the client receives information about the available resources from the REST application. The client does not need to be hardcoded to a fixed set of resources, and the application and client can evolve independently. In other words, the application tells the client where it can go and what it can access by providing it with a simple collection of links to other available resources.

Response JSON

When you build a RESTful web service, consider the style of your response files. Whether they are JSON files, XML files, or in some other format, a good practice is to always have them in a clean and organized form. In the context of HATEOAS, each resource must contain a link reference to itself, commonly referred to as self. Each link also needs a relationship to be associated with it, although no strict rules exist as to how you need to format this relationship. Contain the collection of such links within a _links array, which itself must be a direct property of the resource object. The underscore in the _links property is used so that the property does not collide with any existing fields that are named links. In this guide, you will use the following structure of HATEOAS links:

  "_links": [
    {
      "href": ,
      "rel":
    }
  ]

The following example shows two different links. The first link has a self relationship with the resource object and is generated whenever you register a host. The link points to that host entry in the inventory:

  {
    "href": "http://localhost:9080/inventory/hosts/<hostname>",
    "rel": "self"
  }

The second link has a properties relationship with the resource object and is generated if the host system service is running. The link points to the properties resource on the host:

  {
    "href": "http://<hostname>:9080/system/properties",
    "rel": "properties"
  }

Other formats

Although you should stick to the previous format for the purpose of this guide, another common convention has the link as the value of the relationship:

  "_links": {
      "self": "http://localhost:9080/inventory/hosts/<hostname>",
      "properties": "http://<hostname>:9080/system/properties"
  }

Getting started

The fastest way to work through this guide is to clone the Git repository and use the projects that are provided inside:

git clone https://github.com/openliberty/guide-rest-hateoas.git
cd guide-rest-hateoas

The start directory contains the starting project that you will build upon.

The finish directory contains the finished project that you will build.

Try what you’ll build

The finish directory in the root of this guide contains the finished application. Give it a try before you proceed.

To try out the application, first go to the finish directory and run the following Maven goal to build the application and deploy it to Open Liberty:

mvn liberty:run

After you see the following message, your application server is ready.

The defaultServer server is ready to run a smarter planet.

After the server runs, you can find your hypermedia-driven inventory service at the following URL:

After you are finished checking out the application, stop the Open Liberty server by pressing CTRL+C in the command-line session where you ran the server. Alternatively, you can run the liberty:stop goal from the finish directory in another shell session:

mvn liberty:stop

Creating the response JSON

Navigate to the start directory.

When you run Open Liberty in dev mode, the server listens for file changes and automatically recompiles and deploys your updates whenever you save a new change. Run the following goal to start in dev mode:

mvn liberty:dev

After you see the following message, your application server in dev mode is ready:

Press the Enter key to run tests on demand.

Dev mode holds your command-line session to listen for file changes. Open another command-line session to continue, or open the project in your editor.

Begin by building your response JSON, which is composed of the _links array and the name of the host machine.

Linking to inventory contents

As mentioned before, your starting point is an existing simple inventory REST service.

Take a look at the request handlers in the src/main/java/io/openliberty/guides/microprofile/InventoryResource.java file.

InventoryResource.java

 1// tag::comment[]
 2/*******************************************************************************
 3 * Copyright (c) 2017 IBM Corporation and others.
 4 * All rights reserved. This program and the accompanying materials
 5 * are made available under the terms of the Eclipse Public License v1.0
 6 * which accompanies this distribution, and is available at
 7 * http://www.eclipse.org/legal/epl-v10.html
 8 *
 9 * Contributors:
10 *     IBM Corporation - Initial implementation
11 *******************************************************************************/
12 // end::comment[]
13package io.openliberty.guides.microprofile;
14
15import javax.enterprise.context.ApplicationScoped;
16import javax.inject.Inject;
17import javax.json.JsonArray;
18import javax.json.JsonObject;
19import javax.ws.rs.GET;
20import javax.ws.rs.Path;
21import javax.ws.rs.PathParam;
22import javax.ws.rs.Produces;
23import javax.ws.rs.core.Context;
24import javax.ws.rs.core.MediaType;
25import javax.ws.rs.core.UriInfo;
26
27@ApplicationScoped
28@Path("hosts")
29// tag::InventoryResource[]
30public class InventoryResource {
31
32    @Inject
33    InventoryManager manager;
34
35    // tag::Context[]
36    @Context
37    // end::Context[]
38    // tag::UriInfo[]
39    UriInfo uriInfo;
40    // end::UriInfo[]
41
42    @GET
43    @Produces(MediaType.APPLICATION_JSON)
44    // tag::handler[]
45    public JsonArray handler() {
46        return manager.getSystems(uriInfo.getAbsolutePath().toString());
47    }
48    // end::handler[]
49
50    @GET
51    @Path("{hostname}")
52    @Produces(MediaType.APPLICATION_JSON)
53    // tag::PropertiesForHost[]
54    public JsonObject getPropertiesForHost(@PathParam("hostname") String hostname) {
55        return (hostname.equals("*")) ? manager.list() : manager.get(hostname);
56    }
57    // end::PropertiesForHost[]
58}
59// end::InventoryResource[]

Since the …​/inventory/hosts/ URL will no longer respond with a JSON representation of the contents of your inventory, you can discard the listContents method and integrate it into the getPropertiesForHost method.

Replace the InventoryResource class.
src/main/java/io/openliberty/guides/microprofile/InventoryResource.java

The contents of your inventory are now under the asterisk (*) wildcard and reside at the following URL: http://localhost:9080/inventory/hosts/*

The GET request handler is responsible for handling all GET requests that are made to the target URL. This method responds with a JSON that contains HATEOAS links.

The UriInfo object is what is used to build your HATEOAS links.

The @Context annotation is a part of CDI and indicates that the UriInfo will be injected when the resource is instantiated.

Your new InventoryResource class is now replaced. Next, let’s implement the getSystems method and build the response JSON object.

InventoryManager.java

 1// tag::comment[]
 2/*******************************************************************************
 3 * Copyright (c) 2017, 2019 IBM Corporation and others.
 4 * All rights reserved. This program and the accompanying materials
 5 * are made available under the terms of the Eclipse Public License v1.0
 6 * which accompanies this distribution, and is available at
 7 * http://www.eclipse.org/legal/epl-v10.html
 8 *
 9 * Contributors:
10 *     IBM Corporation - Initial implementation
11 *******************************************************************************/
12 // end::comment[]
13package io.openliberty.guides.microprofile;
14
15import java.util.concurrent.ConcurrentHashMap;
16import java.util.concurrent.ConcurrentMap;
17
18import javax.enterprise.context.ApplicationScoped;
19import javax.json.Json;
20import javax.json.JsonArray;
21import javax.json.JsonArrayBuilder;
22import javax.json.JsonObject;
23import javax.json.JsonObjectBuilder;
24
25import io.openliberty.guides.microprofile.util.ReadyJson;
26import io.openliberty.guides.microprofile.util.InventoryUtil;
27
28@ApplicationScoped
29public class InventoryManager {
30
31    private ConcurrentMap<String, JsonObject> inv = new ConcurrentHashMap<>();
32
33    public JsonObject get(String hostname) {
34        JsonObject properties = inv.get(hostname);
35        if (properties == null) {
36            if (InventoryUtil.responseOk(hostname)) {
37                properties = InventoryUtil.getProperties(hostname);
38                this.add(hostname, properties);
39            } else {
40                return ReadyJson.SERVICE_UNREACHABLE.getJson();
41            }
42        }
43        return properties;
44    }
45
46    public void add(String hostname, JsonObject systemProps) {
47        inv.putIfAbsent(hostname, systemProps);
48    }
49
50    public JsonObject list() {
51        JsonObjectBuilder systems = Json.createObjectBuilder();
52        inv.forEach((host, props) -> {
53            JsonObject systemProps = Json.createObjectBuilder()
54                                         .add("os.name", props.getString("os.name"))
55                                         .add("user.name", props.getString("user.name"))
56                                         .build();
57            systems.add(host, systemProps);
58        });
59        systems.add("hosts", systems);
60        systems.add("total", inv.size());
61        return systems.build();
62    }
63
64    // tag::getSystems[]
65    public JsonArray getSystems(String url) {
66        // inventory content
67        JsonObject content = InventoryUtil.buildHostJson("*", url);
68
69        // collecting systems jsons
70        JsonArrayBuilder jsonArray = inv.keySet().stream().map(host -> {
71            return InventoryUtil.buildHostJson(host, url);
72        }).collect(Json::createArrayBuilder, JsonArrayBuilder::add, JsonArrayBuilder::add);
73
74        jsonArray.add(content);
75
76        return jsonArray.build();
77    }
78    // end::getSystems[]
79
80}

Linking to each available resource

Take a look at your InventoryManager and InventoryUtil files.

Replace the InventoryManager class.
src/main/java/io/openliberty/guides/microprofile/InventoryManager.java

InventoryManager.java

 1// tag::comment[]
 2/*******************************************************************************
 3 * Copyright (c) 2017, 2019 IBM Corporation and others.
 4 * All rights reserved. This program and the accompanying materials
 5 * are made available under the terms of the Eclipse Public License v1.0
 6 * which accompanies this distribution, and is available at
 7 * http://www.eclipse.org/legal/epl-v10.html
 8 *
 9 * Contributors:
10 *     IBM Corporation - Initial implementation
11 *******************************************************************************/
12 // end::comment[]
13package io.openliberty.guides.microprofile;
14
15import java.util.concurrent.ConcurrentHashMap;
16import java.util.concurrent.ConcurrentMap;
17
18import javax.enterprise.context.ApplicationScoped;
19import javax.json.Json;
20import javax.json.JsonArray;
21import javax.json.JsonArrayBuilder;
22import javax.json.JsonObject;
23import javax.json.JsonObjectBuilder;
24
25import io.openliberty.guides.microprofile.util.ReadyJson;
26import io.openliberty.guides.microprofile.util.InventoryUtil;
27
28@ApplicationScoped
29public class InventoryManager {
30
31    private ConcurrentMap<String, JsonObject> inv = new ConcurrentHashMap<>();
32
33    public JsonObject get(String hostname) {
34        JsonObject properties = inv.get(hostname);
35        if (properties == null) {
36            if (InventoryUtil.responseOk(hostname)) {
37                properties = InventoryUtil.getProperties(hostname);
38                this.add(hostname, properties);
39            } else {
40                return ReadyJson.SERVICE_UNREACHABLE.getJson();
41            }
42        }
43        return properties;
44    }
45
46    public void add(String hostname, JsonObject systemProps) {
47        inv.putIfAbsent(hostname, systemProps);
48    }
49
50    public JsonObject list() {
51        JsonObjectBuilder systems = Json.createObjectBuilder();
52        inv.forEach((host, props) -> {
53            JsonObject systemProps = Json.createObjectBuilder()
54                                         .add("os.name", props.getString("os.name"))
55                                         .add("user.name", props.getString("user.name"))
56                                         .build();
57            systems.add(host, systemProps);
58        });
59        systems.add("hosts", systems);
60        systems.add("total", inv.size());
61        return systems.build();
62    }
63
64    // tag::getSystems[]
65    public JsonArray getSystems(String url) {
66        // inventory content
67        JsonObject content = InventoryUtil.buildHostJson("*", url);
68
69        // collecting systems jsons
70        JsonArrayBuilder jsonArray = inv.keySet().stream().map(host -> {
71            return InventoryUtil.buildHostJson(host, url);
72        }).collect(Json::createArrayBuilder, JsonArrayBuilder::add, JsonArrayBuilder::add);
73
74        jsonArray.add(content);
75
76        return jsonArray.build();
77    }
78    // end::getSystems[]
79
80}

The getSystems method accepts a target URL as an argument and returns a JSON object that contains HATEOAS links.

Replace the InventoryUtil class.
src/main/java/io/openliberty/guides/microprofile/util/InventoryUtil.java

InventoryUtil.java

 1// tag::comment[]
 2/*******************************************************************************
 3 * Copyright (c) 2017, 2019 IBM Corporation and others.
 4 * All rights reserved. This program and the accompanying materials
 5 * are made available under the terms of the Eclipse Public License v1.0
 6 * which accompanies this distribution, and is available at
 7 * http://www.eclipse.org/legal/epl-v10.html
 8 *
 9 * Contributors:
10 *     IBM Corporation - Initial implementation
11 *******************************************************************************/
12 // end::comment[]
13package io.openliberty.guides.microprofile.util;
14
15import java.net.HttpURLConnection;
16import java.net.URI;
17import java.net.URL;
18
19import javax.json.Json;
20import javax.json.JsonArray;
21import javax.json.JsonArrayBuilder;
22import javax.json.JsonObject;
23import javax.ws.rs.client.Client;
24import javax.ws.rs.client.ClientBuilder;
25import javax.ws.rs.core.MediaType;
26import javax.ws.rs.core.UriBuilder;
27
28import org.apache.commons.lang3.StringUtils;
29
30public class InventoryUtil {
31
32    private static final int PORT = 9080;
33    private static final String PROTOCOL = "http";
34    private static final String SYSTEM_PROPERTIES = "/system/properties";
35
36    public static JsonObject getProperties(String hostname) {
37        Client client = ClientBuilder.newClient();
38        URI propURI = InventoryUtil.buildUri(hostname);
39        return client.target(propURI)
40                     .request(MediaType.APPLICATION_JSON)
41                     .get(JsonObject.class);
42    }
43
44    // tag::buildHostJson[]
45    public static JsonObject buildHostJson(String hostname, String url) {
46        return Json.createObjectBuilder()
47                   // tag::hostname[]
48                   .add("hostname", hostname)
49                   // end::hostname[]
50                   // tag::links[]
51                   .add("_links", InventoryUtil.buildLinksForHost(hostname, url))
52                   // end::links[]
53                   .build();
54    }
55    // end::buildHostJson[]
56
57    // tag::buildLinksForHost[]
58    public static JsonArray buildLinksForHost(String hostname, String invUri) {
59
60        JsonArrayBuilder links = Json.createArrayBuilder();
61
62        links.add(Json.createObjectBuilder()
63                      .add("href", StringUtils.appendIfMissing(invUri, "/") + hostname)
64                      // tag::self[]
65                      .add("rel", "self"));
66                      // end::self[]
67
68        links.add(Json.createObjectBuilder()
69                .add("href", InventoryUtil.buildUri(hostname).toString())
70                // tag::properties[]
71                .add("rel", "properties"));
72                // end::properties[]
73
74        return links.build();
75    }
76    // end::buildLinksForHost[]
77
78    public static boolean responseOk(String hostname) {
79        try {
80            URL target = new URL(buildUri(hostname).toString());
81            HttpURLConnection http = (HttpURLConnection) target.openConnection();
82            http.setConnectTimeout(50);
83            int response = http.getResponseCode();
84            return (response != 200) ? false : true;
85        } catch (Exception e) {
86            return false;
87        }
88    }
89
90    private static URI buildUri(String hostname) {
91        return UriBuilder.fromUri(SYSTEM_PROPERTIES)
92                .host(hostname)
93                .port(PORT)
94                .scheme(PROTOCOL)
95                .build();
96    }
97
98}

The buildHostJson helper method builds in the InventoryUtil class. It creates a JSON object that contains the hostname of your system and the _links array, which is generated separately in the buildLinksForHost helper method.

This helper accepts a hostname and a target URL as arguments. The helper builds a link that points to the inventory entry with a self relationship and also builds a link that points to the system service with a properties relationship:

  • http://localhost:9080/inventory/hosts/<hostname>

  • http://<hostname>:9080/system/properties

Linking to inactive services or unavailable resources

InventoryUtil.java

 1// tag::comment[]
 2/*******************************************************************************
 3 * Copyright (c) 2017, 2019 IBM Corporation and others.
 4 * All rights reserved. This program and the accompanying materials
 5 * are made available under the terms of the Eclipse Public License v1.0
 6 * which accompanies this distribution, and is available at
 7 * http://www.eclipse.org/legal/epl-v10.html
 8 *
 9 * Contributors:
10 *     IBM Corporation - Initial implementation
11 *******************************************************************************/
12 // end::comment[]
13package io.openliberty.guides.microprofile.util;
14
15import java.net.HttpURLConnection;
16import java.net.URI;
17import java.net.URL;
18
19import javax.json.Json;
20import javax.json.JsonArray;
21import javax.json.JsonArrayBuilder;
22import javax.json.JsonObject;
23import javax.ws.rs.client.Client;
24import javax.ws.rs.client.ClientBuilder;
25import javax.ws.rs.core.MediaType;
26import javax.ws.rs.core.UriBuilder;
27
28import org.apache.commons.lang3.StringUtils;
29
30public class InventoryUtil {
31
32    private static final int PORT = 9080;
33    private static final String PROTOCOL = "http";
34    private static final String SYSTEM_PROPERTIES = "/system/properties";
35
36    public static JsonObject getProperties(String hostname) {
37        Client client = ClientBuilder.newClient();
38        URI propURI = InventoryUtil.buildUri(hostname);
39        return client.target(propURI)
40                     .request(MediaType.APPLICATION_JSON)
41                     .get(JsonObject.class);
42    }
43
44    // tag::buildHostJson[]
45    public static JsonObject buildHostJson(String hostname, String url) {
46        return Json.createObjectBuilder()
47                   // tag::hostname[]
48                   .add("hostname", hostname)
49                   // end::hostname[]
50                   // tag::links[]
51                   .add("_links", InventoryUtil.buildLinksForHost(hostname, url))
52                   // end::links[]
53                   .build();
54    }
55    // end::buildHostJson[]
56
57    // tag::buildLinksForHost[]
58    public static JsonArray buildLinksForHost(String hostname, String invUri) {
59
60        JsonArrayBuilder links = Json.createArrayBuilder();
61
62        links.add(Json.createObjectBuilder()
63                      .add("href", StringUtils.appendIfMissing(invUri, "/") + hostname)
64                      // tag::self[]
65                      .add("rel", "self"));
66                      // end::self[]
67
68        links.add(Json.createObjectBuilder()
69                .add("href", InventoryUtil.buildUri(hostname).toString())
70                // tag::properties[]
71                .add("rel", "properties"));
72                // end::properties[]
73
74        return links.build();
75    }
76    // end::buildLinksForHost[]
77
78    public static boolean responseOk(String hostname) {
79        try {
80            URL target = new URL(buildUri(hostname).toString());
81            HttpURLConnection http = (HttpURLConnection) target.openConnection();
82            http.setConnectTimeout(50);
83            int response = http.getResponseCode();
84            return (response != 200) ? false : true;
85        } catch (Exception e) {
86            return false;
87        }
88    }
89
90    private static URI buildUri(String hostname) {
91        return UriBuilder.fromUri(SYSTEM_PROPERTIES)
92                .host(hostname)
93                .port(PORT)
94                .scheme(PROTOCOL)
95                .build();
96    }
97
98}

Consider what happens when one of the return links does not work or when a link should be available for one object but not for another. In other words, it is important that a resource or service is available and running before it is linked in the _links array.

Although this guide does not cover this case, always make sure that you receive a good response code from a service before you link that service. Similarly, make sure that it makes sense for a particular object to access a resource it is linked to. For instance, it doesn’t make sense for an account holder to be able to withdraw money from their account when their balance is 0. Hence, the account holder should not be linked to a resource that provides money withdrawal.

Running the application

The Open Liberty server was started in development mode at the beginning of the guide and all the changes were automatically picked up.

After the server updates, you can find your new hypermedia-driven inventory service at the following URL:

Testing the hypermedia-driven RESTful web service

At the following URLs, access the inventory service that is now driven by hypermedia:

The first URL returns the current contents of the inventory, and the second URL returns the system properties for localhost. If the inventory does not contain an entry for the host name that is specified in the URL, which is localhost in this case, the system service that is running on the requested host name is called instead. The system properties are retrieved from that system service and then stored in the inventory and returned.

If the servers are running, you can point your browser to each of the previous URLs to test the application manually. Nevertheless, you should rely on automated tests since they are more reliable and trigger a failure if a change introduces a defect.

Setting up your tests

EndpointIT.java

  1// tag::comment[]
  2/*******************************************************************************
  3 * Copyright (c) 2017, 2020 IBM Corporation and others.
  4 * All rights reserved. This program and the accompanying materials
  5 * are made available under the terms of the Eclipse Public License v1.0
  6 * which accompanies this distribution, and is available at
  7 * http://www.eclipse.org/legal/epl-v10.html
  8 *
  9 * Contributors:
 10 *     IBM Corporation - Initial implementation
 11 *******************************************************************************/
 12 // end::comment[]
 13package it.io.openliberty.guides.hateoas;
 14
 15import javax.json.JsonArray;
 16import javax.json.JsonObject;
 17import javax.json.JsonValue;
 18import javax.ws.rs.client.Client;
 19import javax.ws.rs.client.ClientBuilder;
 20import javax.ws.rs.core.Response;
 21
 22import org.apache.cxf.jaxrs.provider.jsrjsonp.JsrJsonpProvider;
 23
 24import org.junit.jupiter.api.*;
 25import org.junit.jupiter.api.MethodOrderer.OrderAnnotation;
 26
 27import static org.junit.jupiter.api.Assertions.assertEquals;
 28import static org.junit.jupiter.api.Assertions.assertTrue;
 29
 30// tag::class[]
 31@TestMethodOrder(OrderAnnotation.class)
 32public class EndpointIT {
 33    // tag::class-contents[]
 34    // tag::setup[]
 35    private String port;
 36    private String baseUrl;
 37
 38    private Client client;
 39
 40    private final String SYSTEM_PROPERTIES = "system/properties";
 41    private final String INVENTORY_HOSTS = "inventory/hosts";
 42
 43    // tag::Before[]
 44    @BeforeEach
 45    // end::Before[]
 46    public void setup() {
 47        // tag::urlCreation[]
 48        port = System.getProperty("http.port");
 49        baseUrl = "http://localhost:" + port + "/";
 50        // end::urlCreation[]
 51
 52        // tag::clientInit[]
 53        client = ClientBuilder.newClient();
 54        client.register(JsrJsonpProvider.class);
 55        // end::clientInit[]
 56    }
 57
 58    // tag::After[]
 59    @AfterEach
 60    // end::After[]
 61    public void teardown() {
 62        client.close();
 63    }
 64    // end::setup[]
 65
 66    /**
 67     * Checks if the HATEOAS link for the inventory contents (hostname=*) is as expected.
 68     */
 69    // tag::Test1[]
 70    @Test
 71    // end::Test1[]
 72    // tag::Order1[]
 73    @Order(1)
 74    // end::Order1[]
 75    // tag::testLinkForInventoryContents[]
 76    public void testLinkForInventoryContents() {
 77        Response response = this.getResponse(baseUrl + INVENTORY_HOSTS);
 78        this.assertResponse(baseUrl, response);
 79
 80        // tag::jsonobj[]
 81        JsonArray sysArray = response.readEntity(JsonArray.class);
 82        // end::jsonobj[]
 83
 84        // tag::assertAndClose[]
 85        String expected, actual;
 86        boolean isFound = false;
 87
 88        for (JsonValue hostValue : sysArray) {
 89            // Try to find the JSON object for hostname *
 90            JsonObject host = hostValue.asJsonObject();
 91            String hostname = host.getJsonString("hostname").getString();
 92
 93            if (hostname.equals("*")) {
 94                // mark that the correct host info was found
 95                isFound = true;
 96                JsonArray links = host.getJsonArray("_links");
 97
 98                expected = baseUrl + INVENTORY_HOSTS + "/*";
 99                actual = links.getJsonObject(0).getString("href");
100                assertEquals(expected, actual, "Incorrect href");
101
102                // asserting that rel was correct
103                expected = "self";
104                actual = links.getJsonObject(0).getString("rel");
105                assertEquals(expected, actual, "Incorrect rel");
106
107                // Exit loop since hostname has been found
108                break;
109            }
110        }
111
112        // If the hostname '*' was not even found, need to fail the testcase
113        assertTrue(isFound, "Could not find system with hostname *");
114
115        response.close();
116        // end::assertAndClose[]
117    }
118    // end::testLinkForInventoryContents[]
119
120    /**
121     * Checks that the HATEOAS links, with relationships 'self' and 'properties' for
122     * a simple localhost system is as expected.
123     */
124    // tag::Test2[]
125    @Test
126    // end::Test2[]
127    // tag::Order2[]
128    @Order(2)
129    // end::Order2[]
130    // tag::testLinksForSystem[]
131    public void testLinksForSystem() {
132        this.visitLocalhost();
133
134        Response response = this.getResponse(baseUrl + INVENTORY_HOSTS);
135        this.assertResponse(baseUrl, response);
136
137        JsonArray sysArray = response.readEntity(JsonArray.class);
138
139        String expected, actual;
140        boolean isHostnameFound = false;
141
142        for (JsonValue hostValue : sysArray) {
143            // Try to find the JSON object for hostname localhost
144            JsonObject host = hostValue.asJsonObject();
145            String hostname = host.getJsonString("hostname").getString();
146
147            if (hostname.equals("localhost")) {
148                isHostnameFound = true;
149                JsonArray links = host.getJsonArray("_links");
150
151                // testing the 'self' link
152                expected = baseUrl + INVENTORY_HOSTS + "/localhost";
153                actual = links.getJsonObject(0).getString("href");
154                assertEquals(expected, actual, "Incorrect href");
155
156                expected = "self";
157                actual = links.getJsonObject(0).getString("rel");
158                assertEquals(expected, actual, "Incorrect rel");
159
160                // testing the 'properties' link
161                expected = baseUrl + SYSTEM_PROPERTIES;
162                actual = links.getJsonObject(1).getString("href");
163                assertEquals(expected, actual, "Incorrect href");
164
165                expected = "properties";
166                actual = links.getJsonObject(1).getString("rel");
167
168                assertEquals(expected, actual, "Incorrect rel");
169
170                break;
171            }
172        }
173
174        // If the hostname 'localhost' was not even found, need to fail the testcase
175        assertTrue(isHostnameFound, "Could not find system with hostname *");
176        response.close();
177
178    }
179    // end::testLinksForSystem[]
180
181    /**
182     * Returns a Response object for the specified URL.
183     */
184    // tag::getResponse[]
185    private Response getResponse(String url) {
186        return client.target(url).request().get();
187    }
188    // end::getResponse[]
189
190    /**
191     * Asserts that the given URL has the correct (200) response code.
192     */
193    // tag::assertResponse[]
194    private void assertResponse(String url, Response response) {
195        assertEquals(200, response.getStatus(), "Incorrect response code from " + url);;
196    }
197    // end::assertResponse[]
198
199    /**
200     * Makes a GET request to localhost at the Inventory service.
201     */
202    // tag::visitLocalhost[]
203    private void visitLocalhost() {
204        Response response = this.getResponse(baseUrl + SYSTEM_PROPERTIES);
205        this.assertResponse(baseUrl, response);
206        response.close();
207        // tag::targetResponse[]
208        Response targetResponse = client.target(baseUrl + INVENTORY_HOSTS + "/localhost")
209                                        .request()
210                                        .get();
211        // end::targetResponse[]
212        targetResponse.close();
213    }
214    // end::visitLocalhost[]
215    // end::class-contents[]
216}
217// end::class[]
Create the EndpointIT class.
src/test/java/it/io/openliberty/guides/hateoas/EndpointIT.java

You can use the @BeforeEach and @AfterEach annotations to perform any setup and teardown tasks for each of your individual tests.

Writing the tests

Each test method must be marked with the @Test annotation. The execution order of test methods is controlled by marking them with the @Order annotation. The value that is passed into the annotation denotes the order in which the methods are run.

The test class contains three helper methods and two test methods:

The getResponse helper method reuses the same line of code for retrieving a response from a specific URL. This technique helps keep your code neat and organized.

The assertResponse helper method ensures that the response that you receive is valid, with a 200 response code.

The visitLocalhost method creates a GET request to the system service, which registers the localhost system.

The testLinkForInventoryContents test is responsible for asserting that the correct HATEOAS link is created for the inventory contents.

Finally, the testLinksForSystem test is responsible for asserting that the correct HATEOAS links are created for the localhost system. This method checks for both the self link that points to the inventory service and the properties link that points to the system service, which is running on the localhost system.

Running the tests

Since you started Open Liberty in dev mode, press the enter/return key to run the tests. You will see the following output:

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running it.io.openliberty.guides.hateoas.EndpointIT
Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.951 s - in it.io.openliberty.guides.hateoas.EndpointIT

Results:

Tests run: 2, Failures: 0, Errors: 0, Skipped: 0

Integration tests finished.

When you are done checking out the service, exit development mode by pressing CTRL+C in the command-line session where you ran the server, or by typing q and then pressing the enter/return key.

Great work! You’re done!

You’ve just built and tested a hypermedia-driven RESTful web service on top of Open Liberty.

Guide Attribution

Creating a hypermedia-driven RESTful web service by Open Liberty is licensed under CC BY-ND 4.0

Copied to clipboard
Copy code block
Copy file contents

Prerequisites:

Nice work! Where to next?

What did you think of this guide?

Extreme Dislike Dislike Like Extreme Like

What could make this guide better?

Raise an issue to share feedback

Create a pull request to contribute to this guide

Need help?

Ask a question on Stack Overflow

Like Open Liberty? Star our repo on GitHub.

Star