KOS Developer's Portal

ApiClient

Introduction

This page explains and shows how to use the KOS system component ApiClient.

Overview

ApiClient

The ApiClient is a KOS-provided system component that you inject into in your code using the @Autowired annotation. You then use it to send HTTP/REST messages to server endpoints.

API Components

This section shows the definitions of the ApiClient class and its associated ResponseEnvelope and ApiRequest classes.

ApiClient

The following code shows the ApiClient class. The method parameters are:

url: the URL endpoint to hit
node: name of destination remote node; if null, then reverts to a local call
body: optional body for POST and PUT calls
headers: map of HTTP headers
clazz: the expected response object
method: the RequestMethod, like GET and POST
timeout: the amount of time, in msec, to wait for a response from a remote node (default is 10 seconds)

API: ApiClient class

public class ApiClient extends AbstractService { (1)

    // Standard methods sending to the local node:
    ResponseEnvelope<T> localGet (String url, Class<T> clazz);
    ResponseEnvelope<T> localPost(String url, Object body, Class<T> clazz);
    ResponseEnvelope<T> localGet (String url, Map<String, Object> headers, Class<T> clazz);
    ResponseEnvelope<T> localPost(String url, Map<String, Object> headers, Object body, Class<T> clazz);

    // Generic method sending to the local node:
    ResponseEnvelope<T> localApi(RequestMethod method, String url, Map<String, Object> headers,
            Object body, Class<T> clazz, int timeout);

    // Standard methods sending to a remote node:
    ResponseEnvelope<T> nodeGet (String node, String url, Class<T> clazz);
    ResponseEnvelope<T> nodePost(String node, String url, Object body, Class<T> clazz);
    ResponseEnvelope<T> nodeGet (String node, String url, Map<String, Object> headers, Class<T> clazz);
    ResponseEnvelope<T> nodePost(String node, String url, Map<String, Object> headers,
            Object body, Class<T> clazz);

    // Generic method sending to a remote node:
    ResponseEnvelope<T> nodeApi(String node, RequestMethod method, String url,
            Map<String, Object> headers, Object body, Class<T> clazz, int timeout)

    // Generic method that uses the ApiRequest object, which defines the full request:
    ResponseEnvelope<T> api(ApiRequest<T> request);
}

1	Extends AbstractService

ResponseEnvelope

The ResponseEnvelope class provides the wrapper around the return values of all API methods.

API: ResponseEnvelope class

@Getter @Setter
public class ResponseEnvelope<T> {
    private int status; (1)
    private ResponseVersion version; (2)
    private T data; (3)
    private String error; (4)
}

1	the HttpStatus value for the API call; 200 = OK, 400 = BAD_REQUEST, etc.
2	contains the version number (major.minor) of the endpoint; used to provide context to the data
3	the actual received payload, as defined in the POST/PUT clazz parameter
4	an optional error message in the event something goes wrong

ApiRequest

The ApiRequest class holds data related to making an RESTful call. It contains field such as HTTP method, URL, headers, request body, response class, and name of destination node. This data object is used with the api(ApiRequest<T> request) method.

API: ApiRequest class

@Getter @Setter
public class ApiRequest<T> {
    private String node;
    private RequestMethod method;
    private String url;
    private Map<String, String> headers;
    private Object body;
    private Class<T> responseClass;
    private int timeout;
}

Example Code

This section demonstrates how to use the ApiClient component to make RESTful calls.

Local GET call

The following example fetches user information by making a call to localGet(). The UserInfo class is simply a data bean that holds fields, which could be ID, first name, last name, or whatever. For our example, it doesn’t matter.

Get user example

public class MyClass {

    @Autowired
    private ApiClient apiClient; (1)

    public UserInfo getUser(int userId) {
        String url = String.format("/api/user/%d", userId); (2)
        ResponseEnvelope<UserInfo> env = apiClient.localGet(url, UserInfo.class); (3)
        return env.getData(); (4)
    }
}

1	The `ApiClient` component is autowired into our `MyClass` object
2	The `url` contains the unique user ID
3	The `localGet()` method is called, expecting `UserInfo` as the return value
4	The return status is not checked; the payload is simply retrieved with the `getData()` call

Remote POST call

Next, we POST data to a server’s endpoint using the nodePost() method.

Save user example

public class MyClass {

    @Autowired
    private ApiClient apiClient;

    public boolean saveUser(UserInfo userInfo) {
        String nodeName = "franken-node"; (1)
        String url = String.format("/api/user/%d", userInfo.getId());
        ResponseEnvelope<Void> env = apiClient.nodePost(nodeName, url, userInfo, Void.class); (2)
        return env.getStatus() == HttpStatus.OK; (3)
    }
}

1	The server is on a node named "franken-node"
2	The `Void` class is used because no response data is expected
3	When the POST method returns, it checks that the return status is OK (200)

PUT call using ApiRequest

This example demonstrates a local PUT call using the ApiRequest class.

Update user example

public class MyClass {

    @Autowired
    private ApiClient apiClient;

    public UserInfo updateUser(UserInfo userInfo) {
        ApiRequest<UserInfo> apiRequest = new ApiRequest<>(); (1)
        apiRequest.setMethod(RequestMethod.POST);
        apiRequest.setUrl("/api/user")
        apiRequest.setBody(userInfo);
        apiRequest.setResponseClass(UserInfo.class);
        ResponseEnvelope<UserInfo> env = apiClient.api(apiRequest); (2)
        return (env.getStatus() == HttpStatus.OK) ? env.getData() : null; (3)
    }
}

1	Create and then populate the `ApiRequest` object
2	Call to the `api()` method
3	If status is OK, then return the updated `UserInfo` object, otherwise return null

Summary

This page has given you a taste of how easy it is to make REST-like API calls using the KOS ApiClient component. Calls can be made to the local node or to any remote node.

Classes mentioned in this article include:

ApiClient
ApiRequest
HttpStatus
ResponseEnvelope
RequestMethod

Next up, we take a look at how the JsonTemplate component is used to make RESTful calls.

ApiClient

Introduction

Overview

API Components

ApiClient

ResponseEnvelope

ApiRequest

Example Code

Local GET call

Remote POST call

PUT call using ApiRequest

Summary

Send us your feedback!