Onboarding a Spring Boot based REST API Service
Onboarding a Spring Boot based REST API Service
This guide is part of a series of guides to onboard a REST API service with the Zowe API Mediation Layer. As an API developer, you can onboard your REST API service built with the Spring Boot framework with the Zowe API Mediation Layer.
Before API ML version 1.2, the API ML provided an integration enabler based on Spring Cloud Netflix components. From version 1.3 and later, the API ML uses a new implementation based on the Plain Java Enabler (PJE) that is not backwards compatible with the previous enabler versions. API ML core services (Discovery Service, Gateway, and API Catalog) support both the old and new enabler versions.
For more information about how to utilize another onboarding method, see:
Outline of onboarding a REST service using Spring Boot
The following steps outline the overall process to onboard a REST service with the API ML using a Spring Boot enabler. Each step is described in further detail in this article.
-
Configuring your Spring Boot based service to onboard with API ML
-
(Optional) Validating the discoverability of your API service by the Discovery Service
-
(Optional) Troubleshooting
Selecting a Spring Boot Enabler
Add a dependency on the Spring Enabler version to your project build configuration that corresponds to the Spring Boot version that you use for the whole project:
- onboarding-enabler-spring-v1
- onboarding-enabler-spring-v2
The process of onboarding an API service is the same for both Spring Boot enabler versions.
Configuring your project
Use either Gradle or Maven as your build automation system to manage your project builds.
You can download the selected enabler artifact from the Zowe Artifactory for latest stable versions.. Alternatively, if you decide to build the API ML from source, it is necessary to publish the enabler artifact to your Artifactory. Publish the enabler artifact by using the Gradle tasks provided in the source code.
Gradle build automation system
Use the following procedure to use Gradle as your build automation system.
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 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 same
build.gradle
file, add the necessary dependencies for your service. If you use the SpringEnabler from the Zowe Artifactory, add the following code block to yourbuild.gradle
script:Use the corresponding artifact according to the Zowe APIML version you are using.
-
For Zowe APIML versions greater than 1.23.5 use the following artifact:
implementation "org.zowe.apiml.sdk:onboarding-enabler-spring:$zoweApimlVersion"
-
For Zowe APIML version 1.23.5 use the following artifact:
implementation "org.zowe.apiml.sdk:onboarding-enabler-spring-v2-springboot-2.3.12.RELEASE:$zoweApimlVersion"
-
For Zowe APIML versions 1.22.3, 1.22.4, and 1.23.0 - 1.23.4 use the following artifact:
implementation "org.zowe.apiml.sdk:onboarding-enabler-spring-v2-springboot-2.3.11.RELEASE:$zoweApimlVersion"
-
For Zowe APIML versions 1.21.6 - 1.21.13 and 1.22.0 - 1.22.2 use the following artifact:
implementation "org.zowe.apiml.sdk:onboarding-enabler-spring-v2-springboot-2.3.9.RELEASE:$zoweApimlVersion"
-
For Zowe APIML versions earlier than 1.21.6 that use Spring 2.1.1 use the following artifact:
implementation "org.zowe.apiml.sdk:onboarding-enabler-spring-v2-springboot-2.1.1.RELEASE:$zoweApimlVersion"
-
For Zowe APIML versions earlier than 1.21.6 that use Spring 1.5.9 use the following artifact:
implementation "org.zowe.apiml.sdk:onboarding-enabler-spring-v1-springboot-1.5.9.RELEASE:$zoweApimlVersion"
Notes:
- You may need to add additional dependencies as required by your service implementation.
- The information provided in this file is valid for
ZoweApimlVersion 1.3.0
and above.
-
-
In your project home directory, run the
gradle clean build
command to build your project. Alternatively, you can rungradlew
to use the specific gradle version that is working with your project.
Maven build automation system
Use the following procedure if you use Maven as your build automation system.
Follow these steps:
-
Add the following XML tags within the newly created
pom.xml
file:<repositories>
<repository>
<id>libs-release</id>
<name>libs-release</name>
<url>https://zowe.jfrog.io/zowe/libs-release/</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>Tip: If you want to use snapshot version, replace libs-release with libs-snapshot in the repository url and change snapshots->enabled to true.
-
Add the proper dependencies
-
For Zowe APIML versions greater than 1.23.5 use the following artifact:
<dependency>
<groupId>org.zowe.apiml.sdk</groupId>
<artifactId>onboarding-enabler-spring</artifactId>
<version>$zoweApimlVersion</version>
</dependency> -
For Zowe APIML version 1.23.5 use the following artifact:
<dependency>
<groupId>org.zowe.apiml.sdk</groupId>
<artifactId>onboarding-enabler-spring-v2-springboot-2.3.12.RELEASE</artifactId>
<version>$zoweApimlVersion</version>
</dependency> -
For Zowe APIML versions 1.22.3, 1.22.4, and 1.23.0 - 1.23.4 use the following artifact:
<dependency>
<groupId>org.zowe.apiml.sdk</groupId>
<artifactId>onboarding-enabler-spring-v2-springboot-2.3.11.RELEASE</artifactId>
<version>$zoweApimlVersion</version>
</dependency> -
For Zowe APIML versions 1.21.6 - 1.21.13 and 1.22.0 - 1.22.2 use the following artifact:
<dependency>
<groupId>org.zowe.apiml.sdk</groupId>
<artifactId>onboarding-enabler-spring-v2-springboot-2.3.9.RELEASE</artifactId>
<version>$zoweApimlVersion</version>
</dependency> -
For Zowe APIML versions earlier than 1.21.6 that use Spring 2.1.1 use the following artifact:
<dependency>
<groupId>org.zowe.apiml.sdk</groupId>
<artifactId>onboarding-enabler-spring-v2-springboot-2.1.1.RELEASE</artifactId>
<version>$zoweApimlVersion</version>
</dependency> -
For Zowe APIML versions earlier than 1.21.6 that use Spring 1.5.9 use the following artifact:
<dependency>
<groupId>org.zowe.apiml.sdk</groupId>
<artifactId>onboarding-enabler-spring-v1-springboot-1.5.9.RELEASE</artifactId>
<version>$zoweApimlVersion</version>
</dependency>
-
-
In the directory of your project, run the
mvn clean package
command to build the project.
Configuring your Spring Boot based service to onboard with API ML
To configure a Spring Boot based service, it is useful to first understand how API ML enabled service Spring Boot based configuration relates to configuration using the Plain Java Enabler.
Spring Boot expects to find the default configuration of an application in an application.yml
file that is placed on the classpath. Typically application.yml
contains Spring Boot specific properties such as properties that are used to start a web application container including TLS security, different spring configuration profiles definitions, and other properties. This application.yml
must contain the Plain Java Enabler API ML service configuration under the apiml.service
prefix. The API ML configuration under this prefix is necessary to synchronize the configuration of apiml.service
with the spring server
configuration.
Configuration properties belong to two categories:
- Service related properties which include endpoints, relative paths, or API documentation definitions.
- Environment related properties which include host names, ports, context etc.
Execution environment related properties should be provided by additional configuration mechanisms that are specific to the target execution environment. Execution environment related properties for development deployments on a local machine differ with those properties on a mainframe system.
-
In a development environment, provide execution environment related properties in an additional
YAML
file with the system property in the following format:-Dspring.config.additional-location=PATH_TO_YAML_FILE
-
On the mainframe system, provide additional configuration properties and values for existing configuration properties through Java system properties.
Execution environments for local development deployments and mainframe deployment are described in detail later in this article.
Follow these steps:
-
Provide a configuration section for onboarding with API ML in the
application.yml
file.-
If you have already onboarded your service with API ML, copy and paste the contents of your existing API ML onboarding configuration file. The default of the API ML onboarding configuration file is the
service-configuration.yml
in theapplication.yml
file under theapiml.service
prefix. -
If you have not yet onboarded your REST service with API ML, use the Sample API Onboarding Configuration to get started.
-
-
If you are reusing your existing API ML onboarding configuration, modify the API ML related properties of the
application.yml
file.a) Remove certain properties under the
apiml.service
section, which must be externalized. Properties for removal are described in the following sample of API ML onboarding configuration.b) Provide the following additional properties under the
apiml
section:enabled: true # If true, the service will automatically register with API ML discovery service.
enableUrlEncodedCharacters: trueThese additional properties are contained in the following sample.
Sample API ML Onboarding Configuration
In the following sample API ML onboarding configuration, properties prefixed with ###
(3 hashtags) indicate that their value must be provided as -Dsystem.property.key=PROPERTY_VALUE
defined in the mainframe execution environment.
The -Dsystem.property.key
must be the same as the flattened path of the YAML property which is commented out with ###
.
These properties must not be defined (uncommented) in your default service YAML configuration file.
Example:
apiml:
service:
### hostname:
In this example from the YAML configuration file, when the application service is run on the mainframe, provide your mainframe hostname value on the Java execution command line in the following format:
-Dapiml.service.hostname=YOUR-MAINFRAME-HOSTNAME-VALUE
Since this value is provided in the Java execution command line, leave the property commented out in the application.yml
.
For development purposes, you can replace or add any property by providing the same configuration structure in an external YAML configuration file. When running your application, provide the name of the external/additional configuration file on the command line in the following format:
-Dspring.config.additional-location=PATH_TO_YOUR_EXTERNAL_CONFIG_FILE
A property notation provided in the format -Dproperty.key=PROPERTY_VALUE
can be used for two purposes:
-
To provide a runtime value for any
YAML
property if${property.key}
is used as its value (after:
) in the YAML configuration fileExample:
some_property_path:
property:
key: ${property.key} -
To add a property to configuration if the property does not already exist
Example:
property:
key: PROPERTY_VALUE
System properties provided with -D
notation on the command line will not replace properties defined
in any of the YAML configuration files.
Authentication properties
These parameters are not required. If a parameter is not specified, a default value is used. See Authentication Parameters for Onboarding REST API Services for more details.
API ML Onboarding Configuration Sample
Some parameters which are specific for your service deployment
are written in ${fill.your.parameterValue}
format. For your service configuration file, provide actual values or externalize your configuration using -D
java commandline parameters.
spring:
application:
name: ${apiml.service.serviceId} # Has to be same as apiml.service.serviceId property
apiml:
enabled: true # Decision if the service should automatically register with API ML discovery service
enableUrlEncodedCharacters: true # Decision if the service requests the API ML GW to receive encoded characters in the URL
service: # The root of API ML onboarding configuration
serviceId: ${fill.your.serviceId} # The symbolic name of the service
title: ${fill.your.title}
description: ${fill.your.description} # API service description
scheme: https
hostname: ${fill.your.hostname} # hostname can be externalized by specifying -Dapiml.service.hostname command line parameter
port: ${fill.your.port} # port can be externalized by specifying -Dapiml.service.port command line parameter
serviceIpAddress: ${fill.your.ipAddress} # serviceIpAddress can be externalized by specifying -Dapiml.service.ipAddress command line parameter
baseUrl: ${apiml.service.scheme}://${apiml.service.hostname}:${apiml.service.port}
contextPath: /${apiml.service.serviceId} # By default the contextPath is set to be the same as apiml.service.serviceId, but doesn't have to be the same
homePageRelativeUrl: ${apiml.service.contextPath}
statusPageRelativeUrl: ${apiml.service.contextPath}/application/info
healthCheckRelativeUrl: ${apiml.service.contextPath}/application/health
discoveryServiceUrls: https://${fill.your.discoveryServiceHost1}:${fill.your.discoveryServicePort1}/eureka # discoveryServiceUrlscan be externalized by specifying -Dapiml.service.discoveryServiceUrls command line parameter
routes:
- gateway-url: "ui/v1"
service-url: ${apiml.service.contextPath}
- gateway-url: "api/v1"
service-url: ${apiml.service.contextPath}/api/v1
- gateway-url: "ws/v1"
service-url: ${apiml.service.contextPath}/ws
authentication:
scheme: httpBasicPassTicket
applid: ZOWEAPPL
apiInfo:
- apiId: zowe.apiml.sampleservice
version: 1.0.0
gatewayUrl: api/v1
swaggerUrl: ${apiml.service.scheme}://${apiml.service.hostname}:${apiml.service.port}${apiml.service.contextPath}/api-doc
documentationUrl: https://www.zowe.org
- apiId: zowe.apiml.sampleservice
version: 2.0.0
gatewayUrl: api/v2
swaggerUrl: ${apiml.service.scheme}://${apiml.service.hostname}:${apiml.service.port}${apiml.service.contextPath}/api-doc?group=apiv2
documentationUrl: https://www.zowe.org
catalog:
tile:
id: cademoapps # Provide ID for your service Catalog tile
title: Sample API Mediation Layer Applications
description: Applications which demonstrate how to make a service integrated to the API Mediation Layer ecosystem
version: 1.0.1
ssl:
## This part configures the http client that connects to Discovery Service. You might reuse your server.ssl.xxx properties that configure your application's servlet.
enabled: true
verifySslCertificatesOfServices: true
protocol: TLSv1.2
enabled-protocols: TLSv1.2
keyStoreType: ${fill.your.keystoretype}
trustStoreType: ${fill.your.truststoretype}
### DEFINE FOLLOWING PROPERTIES IN EXTERNAL CONFIGURATION
keyAlias: ${fill.your.keyAlias}
keyPassword: ${fill.your.keyPassword}
keyStore: ${fill.your..keyStore}
keyStorePassword: ${fill.your.keyStorePassword}
trustStore: ${fill.your.trustStore}
trustStorePassword: ${fill.your.trustStorePassword}
# Optional metadata section
customMetadata:
yourqualifier:
key1: value1
key2: value2
# rest of your configuration
# server: ....
# yourApplicationConfiguration: ....
# and other properties
To determine if your configuration is complete, set the logging level to debug
and run your application. Setting the logging level to 'debug' enables you to troubleshoot issues with certificates for HTTPS and connections with other services.
logging:
level:
ROOT: INFO
org.zowe.apiml: DEBUG
- Provide the suitable parameter corresponding to your runtime environment:
-
For a local machine runtime environment, provide the following parameter on your command line:
-Dspring.config.additional-location=PATH-TO_EXTERNAL-YAML-CONFIG-FILE
At runtime, Spring will merge the two
YAML
configuration files, whereby the properties in the external file have higher priority. -
For a mainframe execution environment, provide environment specific configuration properties. Define these configuration properties and provide them using Java System Properties on the application execution command line.
Important! Ensure that the default configuration contains only properties which are not dependent on the deployment environment. Do not include security sensitive data in the default configuration.
Note: For details about the configuration properties, see Configuring your service in the article Onboarding a REST API service with the Plain Java Enabler (PJE).