Skip to main content
Version: v1.18.x LTS

Onboarding a Spring Boot based REST API Service

Last updated
:  |
0 min read
|
Edit this page
 PDF
 Open doc issue

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.

  1. Selecting a Spring Boot Enabler

  2. Configuring your project

  3. Configuring your Spring Boot based service to onboard with API ML

  4. Registering and unregistering your service with API ML

  5. Adding API documentation

  6. (Optional) Validating your API service discoverability

  7. (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

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:

  1. Create a gradle.properties file in the root of your project if one does not already exist.

  2. 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/

  3. Add the following Gradle code block to the repositories section of your build.gradle file:

    repositories {
    ...
    maven {
    url artifactoryMavenRepo
    }
    }

  4. 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 Spring version you are using.

    • For Spring boot version 2.1.1, use the following artifact:

      implementation "org.zowe.apiml.sdk:onboarding-enabler-spring-v2-springboot-2.1.1.RELEASE:$zoweApimlVersion"

    • For Spring boot version 1.5.9, use the following artifact:

      implementation "org.zowe.apiml.sdk:onboarding-enabler-spring-v1-springboot-2.1.1.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.

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

  1. 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.

  2. Add the proper dependencies

    2.1 For spring version 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>

    2.2 For spring version 1.5.9, use the following artifact

    <dependency>
    <groupId>org.zowe.apiml.sdk</groupId>
    <artifactId>onboarding-enabler-spring-v1-springboot-2.1.1.RELEASE</artifactId>
    <version>$zoweApimlVersion</version>
    </dependency>

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

  1. 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.

  2. 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.

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: org.zowe.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: org.zowe.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
  1. 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:

  1. 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>

  2. 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<>()
    ));
    }
    }

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

  1. Validate successful onboarding

  2. Check that you can access your API service endpoints through the Gateway.

  3. (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.

On this page