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.
Note: 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 systemCurrently, the only build automation system for use with onboarding a Micronaut based service is Gradle.
Follow these steps:
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 artifactartifactoryMavenRepo=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 applicationUse 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 configurationUse 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 configuration
where:
fill.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}
Note: 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 configurationOnce you complete API ML configuration, add configuration to provide correct mapping between API ML and micronaut parameters.
Follow these steps:
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}
where:
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 configurationSet 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 registrationAfter you complete the configuration, ensure that your application is visible within Zowe API ML. For more information, see the article validating the discoverability of your API service by teh Discovery Service, which describes the validation procedure common for all enablers.