Client Walkthrough
This guide provides a walkthrough of how to generate a client library for a kdb Insights service using an OpenAPI client generator.
The languages covered explicitly are
using the Swagger Codegen generator.
You can follow similar steps for any of the wide variety of languages that Swagger Codegen supports! See the full list here
You can also use a different code generation tool if you prefer, however the exact commands in this walkthrough will no longer be applicable.
This walkthrough uses the OpenAPI specification for the kdb Insights Discovery service to provide concrete examples, this can easily be replaced by any of the OpenAPI specifications for the services provided by KX.
Prerequisites
Create a folder to use as the root directory for the walkthrough
$ mkdir open-api-clients && cd open-api-clients
All commands will be relative to this directory unless otherwise stated.
Download the Swagger Codegen CLI.
$ CLI_VERSION=3.0.26
$ wget -q https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/$CLI_VERSION/swagger-codegen-cli-$CLI_VERSION.jar -O swagger-codegen-cli.jar
Version 3.0.26 is the latest version of the tool available at the time of writing.
Java
First complete the prerequisites if you haven't already.
The steps that we are going to complete are
- Download the OpenAPI specification for the kdb Insights Discovery service.
- Use the
swagger-codegen-cli.jar
to generate a Java SDK - Create a project that uses the generated SDK
Downloading the spec
Download the kdb Insights Discovery service OpenAPI specification from the kdb Insights API documentation
$ wget -q <url-to-OpenAPI-spec> -O discovery.json
Generating the SDK
Generate a java client library using the swagger-codegen-cli.jar
from the prerequisites and the discovery.json
spec.
$ cat config.json
{
"hideGenerationTimestamp": "true"
}
$ java -jar swagger-codegen-cli.jar generate -c config.json -l java -i discovery.json -o java-discovery-sdk
There will be an auto-generated README.md in java-discovery-sdk
that explains how to use this client library.
Using the SDK
We will cover the steps to use this in a Maven project.
You can now install the SDK locally with Maven using
$ cd java-discovery-sdk
$ mvn clean install
If you experience issues installing the SDK, see our troubleshooting section for possible solutions.
It can now be referenced as a dependency in other local projects if you add the following dependency to your pom.xml
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-java-client</artifactId>
<version>1.0.0</version>
<scope>compile</scope>
</dependency>
Once this is done you can create an example call that uses the io.swagger.client
package as follows
import io.swagger.client.*;
import io.swagger.client.auth.*;
import io.swagger.client.model.*;
import io.swagger.client.api.DiscoveryApi;
import java.io.File;
import java.util.*;
public class DiscoveryApiExample {
public static void main(String[] args) {
ApiClient client = new ApiClient();
client.setBasePath("http://localhost:5000");
DiscoveryApi apiInstance = new DiscoveryApi(client);
try {
ServiceTable result = apiInstance.getServices();
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling DiscoveryApi#getServices");
e.printStackTrace();
}
}
}
If you run this and there is a valid discovery proxy at localhost:5000
that has some services registered with it, then you will see some output similar to
class ServiceTable {
[class ServiceTableInner {
uid: RDB:5444
service: RDB
ip: 172.18.0.7
hostname: 4764daa74c43
port: 5444
status: UP
metadata: {instanceId=4764daa74c43:RDB:5444, byteKey=0100000028000000630b0001000000636f6e6e6563746976697479000b00010000006165726f6e00}
}, class ServiceTableInner {
uid: LR:5445
service: LR
ip: 172.18.0.3
hostname: 279e7d45bd4a
port: 5445
status: UP
metadata: {instanceId=279e7d45bd4a:LR:5445, byteKey=0100000028000000630b0001000000636f6e6e6563746976697479000b00010000006165726f6e00}
}, class ServiceTableInner {
uid: 2c04c966caf4:KXI-DISCOVERY:8761
service: KXI-DISCOVERY
ip: 172.18.0.2
hostname: registry-0
port: 8761
status: UP
metadata: {management.port=8761}
}]
}
In this example the discovery proxy has three services registered with it
- LR
- RDB
- KXI-DISCOVERY
Troubleshooting
Depending on the version of Java you are using you may need to complete some extra steps to build and install the autogenerated project.
If you see the error
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:2.10.4:jar (attach-javadocs) on project
swagger-java-client: MavenReportException: Error while generating Javadoc: Unable to find javadoc command: The environment
variable JAVA_HOME is not correctly set. -> [Help 1]
during the install, upgrade the version of the maven-javadoc-plugin to 3.3.0
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.3.0</version>
...
</plugin>
If you see the error
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.1:compile (default-compile) on project
swagger-java-client: Compilation failure: Compilation failure:
[ERROR] /code/java-discovery-sdk/src/main/java/io/swagger/client/model/ServiceEntry.java:[28,18] package
javax.annotation does not exist
...
during install, this is because javax.annotation is no longer a part of the JRE from Java 11. This can be resolved by adding it as a dependency explicitly in the pom.xml
<!-- https://mvnrepository.com/artifact/javax.annotation/javax.annotation-api -->
<dependency>
<groupId>javax.annotation</groupId>
<artifactId>javax.annotation-api</artifactId>
<version>1.3.2</version>
</dependency>
Javascript
First complete the prerequisites if you haven't already.
The steps that we are going to complete are
- Download the OpenAPI specification for the kdb Insights Discovery service.
- Use the
swagger-codegen-cli.jar
to generate a Javascript SDK - Create a project that uses the generated SDK
The versions of npm
and node
used in this walkthrough are
$ npm --version
7.11.2
$ node --version
v12.21.0
Downloading the spec
Download the kdb Insights Discovery service OpenAPI specification from the kdb Insights API documentation
$ wget -q <url-to-OpenAPI-spec> -O discovery.json
Generating the SDK
Generate a javascript client library using the swagger-codegen-cli.jar
from the prerequisites and the discovery.json
spec.
$ java -jar swagger-codegen-cli.jar generate -l javascript -i discovery.json -o js-discovery-sdk
There will be an auto-generated README.md in js-discovery-sdk
that explains how to use this client library and documentation on the specific classes in docs
.
Using the SDK
We will cover the steps to use this in a Node.js project.
First, we need to install the dependencies for the generated and edit the package.json
to specify that the package type of the SDK is a module
.
$ cd js-discovery-sdk
$ npm install
$ vi package.json
{
...
"type": "module",
...
}
$ cd ..
Create a new folder to house the project that will use the SDK and install the SDK as a dependency
$ mkdir js-client && cd js-client
$ npm install ../js-discovery-sdk --save
You should now have folder structure like
$ ls
node_modules package.json package-lock.json
We will use this project as a module, so you will need to set the package type to be module
in the package.json
$ vi package.json
{
"type": "module",
...
}
Create a file called main.js
that contains
import * as kx from 'kx_insights_service_discovery';
var client = new kx.ApiClient();
client.basePath = "http://localhost:5000";
var api = new kx.DiscoveryApi(client);
api.getServices((error, data, response) => {
if (error) {
console.error(error);
} else {
console.log(JSON.stringify(data, null, 2));
}
});
You can run your main.js
with
$ node --experimental-specifier-resolution=node main.js
!!! Note The argument '--experimental-specifier-resolution=node' is required because the generated SDK uses relative paths
See [here](https://nodejs.org/api/esm.html#esm_customizing_esm_specifier_resolution_algorithm) for more information
If you run this and there it a valid discovery proxy at localhost:5000
it will print out the services in the discovery registry.
Depending on what is registered with your discovery service you will see something like
[
{
"uid": "RDB:5444",
"service": "RDB",
"ip": "172.18.0.2",
"hostname": "4764daa74c43",
"port": 5444,
"status": "UP",
"metadata": {
"instanceId": "4764daa74c43:RDB:5444",
"byteKey": "0100000028000000630b0001000000636f6e6e6563746976697479000b00010000006165726f6e00"
}
},
{
"uid": "LR:5445",
"service": "LR",
"ip": "172.18.0.3",
"hostname": "279e7d45bd4a",
"port": 5445,
"status": "UP",
"metadata": {
"instanceId": "279e7d45bd4a:LR:5445",
"byteKey": "0100000028000000630b0001000000636f6e6e6563746976697479000b00010000006165726f6e00"
}
},
{
"uid": "2c04c966caf4:KXI-DISCOVERY:8761",
"service": "KXI-DISCOVERY",
"ip": "172.18.0.5",
"hostname": "registry-0",
"port": 8761,
"status": "UP",
"metadata": {
"management.port": "8761"
}
}
]
In this example the discovery proxy has three services registered with it
- LR
- RDB
- KXI-DISCOVERY