Onboarding a Micronaut based REST API service
Onboarding a Micronaut based REST API service
As an API developer, you can onboard a REST service to the Zowe API Mediation Layer using the Micronaut framework. While using the Spring framework to develop a JVM-based service to register to the API ML is the recommended method, you can use the procedure described in this article to onboard a service using the Micronaut framework.
For more information about onboarding API services with the API ML, see the Onboarding Overview.
For Micronaut-related documentation, see the Micronaut website.
- Set up your build automation system
- Configure the Micronaut application
- Validate successful registration
Set up your build automation system
Currently, the only build automation system for use with onboarding a Micronaut based service is Gradle.
-
Create a
gradle.properties
file in the root of your project if one does not already exist. -
In the
gradle.properties
file, set the URL of the specific Artifactory containing the SpringEnabler artifact.# Repository URL for getting the enabler-java artifact
artifactoryMavenRepo=https://zowe.jfrog.io/zowe/libs-release/ -
Add the following Gradle code block to the
repositories
section of yourbuild.gradle
file:repositories {
...
maven {
url artifactoryMavenRepo
}
} -
In the
build.gradle
file, add the micronaut enabler as a dependency:implementation "org.zowe.apiml.sdk:onboarding-enabler-micronaut:$zoweApimlVersion"
-
(Optional) Add a shadow plug-in to create a runnable jar file. Update the
gradle.build file
with a plugin:id 'com.github.johnrengelman.shadow' version '6.1.0'
-
Specify the main class with the following script:
mainClassName = '${your.packa.name.MainClassName}' #replace with your main class
-
Define the output jar file.
Add the following script to define the output of the jar file:
shadowJar {
archiveBaseName.set('micronaut-enabler')
archiveClassifier.set('')
archiveVersion.set('1.0')
}The following example shows a sample
gradle.build
file:Example:
plugins {
id "io.micronaut.application" version '1.0.5'
id 'com.github.johnrengelman.shadow' version '6.1.0'
}
mainClassName = 'org.zowe.apiml.Application'
shadowJar {
archiveBaseName.set('micronaut-enabler')
archiveClassifier.set('')
archiveVersion.set('1.0')
}
version "0.1"
group "org.zowe.apiml"
repositories {
url artifactoryMavenRepo
}
micronaut {
version = "2.1.3"
runtime "netty"
testRuntime "junit5"
processing {
incremental true
annotations "org.zowe.apiml.*"
}
}
dependencies {
implementation "org.zowe.apiml. sdk:onboarding-enabler-micronaut:$zoweApimlVersion"
}
java {
sourceCompatibility = JavaVersion.toVersion('1.8')
targetCompatibility = JavaVersion.toVersion('1.8')
} -
(Optional) Create a shadow jar.
To create a shadow jar, execute the gradle
shadowJar
task. For this sample, the plugin produces the jarmicronaut-enabler-1.0.jar
inbuild/libs
directory.You can now run your application with the command
java -jar micronaut-enabler-1.0.jar
. -
Start the application.
From the root directory of your project, start the application with the
gradle run
command.
Configure the Micronaut application
Use a yaml file to configure your Micronaut application. Create the following two sections in your yaml file:
apiml
for API ML configurationmicronaut
for micronaut configuration
Add API ML configuration
Use the following procedure to add API ML configuration to the application.yaml.
Follow these steps:
-
Add the following configuration to the
apiml
section in the yaml file:apiml:
enabled: true
service:
serviceId: ${fill.your.serviceId} # The symbolic name of the service
#rest of the configurationfill.your.service
Specifies the ID of your service
-
Add SSL-resolving properties as shown in the following example. Ensure that you structure the nested objects within
apiml.service
as arrays. Be sure to include-
(hyphen) beforeenabled
thereby indicating the first element of the array.
Example:
apiml:
service:
ssl:
- enabled: true
verifySslCertificatesOfServices: true
protocol: TLSv1.2
enabled-protocols: TLSv1.2
keyStoreType: ${fill.your.keystoretype}
trustStoreType: ${fill.your.truststoretype}
keyAlias: ${fill.your.keyAlias}
keyPassword: ${fill.your.keyPassword}
keyStore: ${fill.your..keyStore}
keyStorePassword: ${fill.your.keyStorePassword}
trustStore: ${fill.your.trustStore}
trustStorePassword: ${fill.your.trustStorePassword}
ciphers: ${fill.your.ciphers}
For a sample of this configuration, see API ML Onboarding Configuration Sample.
The yaml now contains configuration to register to the API Mediation Layer.
Add Micronaut configuration
Once you complete API ML configuration, add configuration to provide correct mapping between API ML and micronaut parameters.
-
Add the following yaml snippet with the micronaut configuration parameters:
micronaut:
application:
name: ${apiml.service.serviceId}
server:
port: ${apiml.service.port}
context-path: /${apiml.service.serviceId}
ssl:
enabled: true
key-store:
password: ${apiml.service.ssl[0].keyPassword}
type: ${apiml.service.ssl[0].keyStoreType}
path: file:${apiml.service.ssl[0].keyStore}
key:
alias: ${apiml.service.ssl[0].keyAlias}
password: ${apiml.service.ssl[0].keyPassword}
trust-store:
password: ${apiml.service.ssl[0].trustStorePassword}
path: file:${apiml.service.ssl[0].trustStore}
type: ${apiml.service.ssl[0].trustStoreType}
port: ${apiml.service.port}
ciphers: ${apiml.service.ssl[0].ciphers}
protocol: ${apiml.service.ssl[0].protocol}-
apiml.service.serviceId
Specifies the ID of your service -
apiml.service.port
Specifies the port on which the service listens -
apiml.service.ssl[0].keyPassword
Specifies the password that protects the key in keystore -
apiml.service.ssl[0].keyStoreType
Specifies the type of the keystore, (Example: PKCS12) -
apiml.service.ssl[0].keyStore
Specifies the location of the keystore -
apiml.service.ssl[0].keyAlias
Specifies the alias under which the key is stored in the keystore -
apiml.service.ssl[0].trustStorePassword
Specifies the password that protects the certificates in the truststore -
apiml.service.ssl[0].trustStore
Specifies the location of the truststore -
apiml.service.ssl[0].trustStoreType
Specifies the type of the truststore, (Example: PKCS12) -
apiml.service.ssl[0].ciphers
Specifies the list of ciphers that user wants to enable for TLS communication -
apiml.service.ssl[0].protocol
Specifies the type of SSL/TLS protocol (Example: TLSv1.2)
-
(Optional) Set up logging configuration
Set up custom logging configuration to have more structured output and better control of logs.
Create a logback.xml
file in the resources
folder and include the application.yml
. Update the logback.xml
file with the following configuration:
<configuration>
<property resource="application.yml" />
<turboFilter class="ch.qos.logback.classic.turbo.DuplicateMessageFilter">
<AllowedRepetitions>0</AllowedRepetitions>
</turboFilter>
<conversionRule conversionWord="clr" converterClass="org.springframework.boot.logging.logback.ColorConverter" />
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
<encoder>
<pattern>%cyan(%d{yyyy-MM-dd HH:mm:ss.SSS,UTC}) %gray(<${logbackService:-${logbackServiceName}}:%thread:${PID:- }>){magenta} %X{userid:-} %highlight(%-5level) %magenta(\(%logger{15}\)){cyan} %msg%n</pattern>
</encoder>
</appender>
<root level="info">
<appender-ref ref="STDOUT" />
</root>
</configuration>
Validate successful registration
After you complete the configuration, ensure that your application is visible within Zowe API ML. For more information, see Validating the discoverability of your API service by the Discovery Service, which describes the validation procedure common for all enablers.