Version: v2.12.x LTS

Onboarding a Spring Boot based REST API Service

Last updated

: 3/8/2024|

... min read

Edit this page

Open doc issue

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.

Note: 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.

Tip: 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.

Selecting a Spring Boot Enabler
Configuring your project
- Gradle build automation system
- Maven build automation system
Configuring your Spring Boot based service to onboard with API ML
Registering and unregistering your service with API ML
- Unregistering your service with API ML
- Basic routing
Adding API documentation
(Optional) Validating the discoverability of your API service by the Discovery Service
(Optional) Troubleshooting
- Log messages during registration problems

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

Note: 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.

Note: 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 your build.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 your build.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 run gradlew 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 the application.yml file under the apiml.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: true
```
These 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 file

Example:
```
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
```

Note: 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

Tip: 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).

SAF Keyring configuration

You can choose to use a SAF keyring instead of keystore and truststore for storing certificates. For information about required certificates, see Zowe API ML TLS requirements. For information about running Java on z/OS with a keyring, see SAF Keyring. Make sure that the enabler can access and read the keyring. Please refer to documentation of your security system for details.

The following example shows enabler configuration with keyrings:

ssl:
    keyAlias: localhost
    keyPassword: password
    keyStore: safkeyring://my_racf_id/my_key_ring
    keyStorePassword: password
    keyStoreType: JCERACFKS
    trustStore: safkeyring://my_racf_id/my_key_ring
    trustStoreType: JCERACFKS
    trustStorePassword: password

Custom Metadata

Custom metadata are described here.

Registering and unregistering your service with API ML

Onboarding a REST service to the API ML means registering the service with the API ML Discovery Service. The registration is triggered automatically by Spring after the service application context is fully initialized by firing a ContextRefreshed event.

To register your REST service with API ML using a Spring Boot enabler, annotate your application main class with @EnableApiDiscovery.

Unregistering your service with API ML

Unregistering a service onboarded with API ML is done automatically at the end of the service application shutdown process in which Spring fires a ContextClosed event. The Spring onboarding enabler listens for this event and issues an unregister REST call to the API ML Discovery Service.

Basic routing

See API ML Basic Routing for more information about basic routing in the API ML.

Adding API documentation

Use the following procedure to add Swagger API documentation to your project.

Follow these steps:

Add a SpringFox Swagger dependency.

For Gradle, add the following dependency in build.gradle:
```
compile "io.springfox:springfox-swagger2:2.9.2"
```

For Maven, add the following dependency in pom.xml:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

Add a Spring configuration class to your project.

Example:

package org.zowe.apiml.sampleservice.configuration;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfiguration extends WebMvcConfigurerAdapter {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.ant("/api/v1/**"))
            .build()
            .apiInfo(new ApiInfo(
                "Spring REST API",
                "Example of REST API",
                "1.0.0",
                null,
                null,
                null,
                null,
                new ArrayList<>()
            ));
    }

    @Bean
    public Docket apiv2() {
        return new Docket(DocumentationType.SWAGGER_2)
            .groupName("apiv2")
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.ant("/api/v2/**"))
            .build()
            .apiInfo(new ApiInfo(
                "Spring REST API",
                "Example of REST API",
                "1.0.0",
                null,
                null,
                null,
                null,
                new ArrayList<>()
            ));
    }
}

Customize this configuration according to your specifications. For more information about customization properties, see Springfox documentation.

Note: The current SpringFox Version 2.9.2 does not support OpenAPI 3.0. For more information about the open feature request see this issue.

Validating the discoverability of your API service by the Discovery Service

Once you build and start your service successfully, you can use the option of validating that your service is registered correctly with the API ML Discovery Service.

Follow these steps:

Validate successful onboarding
Check that you can access your API service endpoints through the Gateway.
(Optional) Check that you can access your API service endpoints directly outside of the Gateway.

Specific addresses and user credentials for the individual API ML components depend on your target runtime environment.

Note: If you are working with local installation of API ML and you are using our dummy identity provider, enter user for both username and password. If API ML was installed by system administrators, ask them to provide you with actual addresses of API ML components and the respective user credentials.

Tip: Wait for the Discovery Service to fully register your service. This process may take a few minutes after your service was successfully started.

Troubleshooting

Log messages during registration problems

When an Enabler connects to the Discovery Service and fails, an error message prints to the Enabler log. The default setting does not suppress these messages as they are useful to resolve problems during the Enabler registration. Possible reasons for failure include the location of Discovery Service is not correct, the Discovery Service is down, or the TLS certificate is invalid. These messages continue to print to the Enabler log, while the Enabler retries to connect to the Discovery Service.

To fully suppress these messages in your logging framework, set the log levels to OFF on the following loggers:

com.netflix.discovery.DiscoveryClient, com.netflix.discovery.shared.transport.decorator.RedirectingEurekaHttpClient

Some logging frameworks provide other tools to suppress repeated messages. Consult the documentation of the logging framework you use to find out what tools are available. The following example demonstrates how the Logback framework can be used to suppress repeated messages.

Example:

The Logback framework provides a filter tool, DuplicateMessageFilter.

Add the following code to your configuration file if you use XML configuration:

    <turboFilter class="ch.qos.logback.classic.turbo.DuplicateMessageFilter">
        <AllowedRepetitions>0</AllowedRepetitions>
    </turboFilter>

Note: For more information, see the full configuration used in the Core Services in GitHub.

Onboarding a Spring Boot based REST API Service

Outline of onboarding a REST service using Spring Boot​

Selecting a Spring Boot Enabler​

Configuring your project​

Gradle build automation system​

Maven build automation system​

Configuring your Spring Boot based service to onboard with API ML​

Sample API ML Onboarding Configuration​

Authentication properties​

API ML Onboarding Configuration Sample​

SAF Keyring configuration​

Custom Metadata​

Registering and unregistering your service with API ML​

Unregistering your service with API ML​

Basic routing​

Adding API documentation​

Validating the discoverability of your API service by the Discovery Service​

Troubleshooting​

Log messages during registration problems​

Outline of onboarding a REST service using Spring Boot

Selecting a Spring Boot Enabler

Configuring your project

Gradle build automation system

Maven build automation system

Configuring your Spring Boot based service to onboard with API ML

Sample API ML Onboarding Configuration

Authentication properties

API ML Onboarding Configuration Sample

SAF Keyring configuration

Custom Metadata

Registering and unregistering your service with API ML

Unregistering your service with API ML

Basic routing

Adding API documentation

Validating the discoverability of your API service by the Discovery Service

Troubleshooting

Log messages during registration problems