Package structure

A generated service will have the following architecture (example service "MyService"):

The generated base package is "com.apiomat.microservice.{serviceName}", it contains:

• The Spring Boot application main class, named after the service with "Application" appended (e.g. MyServiceApplication.java). It contains annotations to start the Spring Boot application and enable Feign:

  MyServiceApplication.java

  @SpringBootApplication

  @EnableFeignClients

  public class MyServiceApplication extends SpringBootServletInitializer

• The main Spring-related configuration, "{serviceName}Configuration.java", that contains the configuration and initialization of all the beans required for your service logic.

• The "config" package which contains:

  • A SwaggerDocumentationConfig.java class, which contains specific configuration to generate an OpenAPI specification. This is done for all REST endpoints annotated with the @ApiXXX swagger annotations from the springfox-swagger2 library. The OpenAPI specification is available by default at http://localhost:8090/{lowerCaseServiceName}/v2/api-docs and is accessed by the Explorer service to display the API documentation UI.

  • A "{serviceName}ConfigDefinition.java" class that contains the specific ApiOmat application configuration definition of your service. See Configuration Parameters.

  • A "{serviceName}CorsConfiguration.java" class that contains the CORS configuration for your service. See CORS configuration.

• The "controller" package which contains the following for each class:

  • An API interface "I{className}Api.java" that describes API endpoints.

  • An API implementation "{className}ApiController.java" to call internal service logic.

• The "model" package which contains the following for each class:
  

  • A POJO "{className}.java" that holds the class's attributes.

  • An enum list of reference attributes "{className}RefAttributes.java", used when querying the data model's reference endpoints.

  • An enum list of static data attributes name "{className}StaticDataAttributes.java", used when querying the data model's static data endpoints.

• The "service" package which contains the following for each class :

  • A Feign client "{className}ApiClient.java" that calls the corresponding Yambas endpoints when a data model's CRUD operations are executed.

  • An API abstract service "Abstract{className}ApiService.java" that provides default implementations of service methods.

  • An API service implementation "{className}ApiServiceImpl.java" that extends the abstract implementation, where the developer can make their own implementations of service methods by overriding the default abstract provided ones.

The resources folder contains:

• The "application.yml" Spring configuration file, with specific values described below in the Service Configuration - Spring related configuration section.

• A "logback.xml" logging configuration file, see Logging and Debugging for details on this

• You can place your own logo for the service here. For details see section Add logo for marketplace

Versioning

ApiOmat 21.03 gives you the possibility to version your service projects independently from the "API" version (the version of your service in Yambas). That way, your service project may have a version that reflects the version of your project or business logic, while the API version stays same. This means, that you may have a project/artifact version "1.1.15", while your "API" or service version that is shown in the dashboard and attached to the is still "1.1.0"
To achieve that, there's a new property in the application.yml with the key apiomat.service.version. By default, this property has a placeholder as value. The placeholder comes from the pom.xml's property section with the key apiomat.service.version which is replaced during the maven build. Therefore, we recommend changing the property within the pom.xml, as the placeholder may be contained in the application.yml several times. Services that are generated with an ApiOmat 21.03 version automatically contain this structure.

During the artifact processing, Yambas scans at first for the property in the application.yml. If it isn't present or contains the placeholder, it will try to find the respective value in the properties section of the pom.xml. If the property doesn't exist as well, it will fall back to the version that is specified in the pom.xml. This value is used as service version in Yambas (and it's respective API endpoints).

The "used service" dependency libraries will use the service version and not the project version as well, as these libraries contain the clients and models that are bound to the API version. The same applies for the executor endpoints.

Maven dependencies

In this section, we'll list the dependencies that are defined in the pom.xml of your generated service and explain what each of them is for. Links to related documentation will be provided when relevant.

Maven plugins

The pom.xml of your generated service will have the following Maven plugins:

Application main class

The entry point of your service is its application class {ServiceName}Application.java. It contains a main method and is annotated with @SpringBootApplication which is explained in more detail in the Spring Boot documentation .

An important feature to be aware of when using @SpringBootAnnotation is the @ComponentScan annotation. By default, a bean will be created and added to your service's application context for all classes annotated with @Component (or its child annotations such as @Service or @Controller) from the package where your @SpringBootAnnotation annotated class is located, and from all sub package s.

Service Configuration

Configuration via properties is a key part of Spring. Typically, you can define your application configuration in a YAML or properties file (e.g. in your generated service, there will be an application.yml file) .

# Your service's context-path and static port
server:
  servlet:
        context-path: /{YOUR_SERVICE_NAME_LOWERCASE}/v/@project.version@
  port: 8090


spring:
  # Application name and version are placeholders, the values are taken from your service's pom.xml
  application:
        name: '@name@'
        version: '@project.version@'
  jmx:
      default-domain: '@name@'
  cloud:
      # Configuration for Consul
      consul:
		  # The host and port of your Consul installation
          host: localhost
          port: 8500
		  # Service discovery properties
          discovery:
			  # Specific meta data of your service instance in Consul
			  # Services must provide a context path and version so they can be queried through the Dispatcher gateway
			  # "registerAsYambasContextPath" is also used in the Gateway context to proxy requests over YAMBAS to your service
              tags: contextPath=${server.servlet.context-path}, version='@project.version@', registerAsYambasContextPath
              enabled: true
			  # Path used by Consul to assert your service's healthiness, the Spring Actuator endpoint is used there
              health-check-path: ${server.servlet.context-path}/actuator/health
			  health-check-critical-timeout

  # Object mapping configuration for timestamps
  jackson:
      deserialization:
          read-date-timestamps-as-nanoseconds: false
      serialization:
          write-date-timestamps-as-nanoseconds: false
          write-dates-as-timestamps: true

  # If you want to enable zipkin tracing, you have to add at least the commented-out values and set sleuth and zipkin to enabled
  # A probability of 1.0 will trace ALL requests.
  # Note that this may consume more memory, so you may have to increase the Xmx value of the JVM
  zipkin:
    enabled: false
  #  baseUrl: localhost:9411
  sleuth:
    enabled: false
  #  sampler:
  #    probability: 1.0

# Path where your service will expose the OpenAPI specification generated by SpringFox annotations on your API methods
# This is the default one, used by the API Docs service Explorer
springfox:
  documentation:
    swagger:
      v2:
        path: /v2/api-docs


# Specific configuration for Feign client communicating with YAMBAS
feign:
  client:
    config:
      YAMBAS:
		# Set the connection and read timeout to 5 seconds
        connectTimeout: 5000
        readTimeout: 5000
		# A specific request interceptor implementation, for Feign clients communicating with YAMBAS, that copies the incoming request's headers to the outgoing request
        requestInterceptors:
          - com.apiomat.service.base.feign.RequestHeaderRequestInterceptor


# Service ID, allowed version(s) and path prefix of YAMBAS, used to configure Feign clients
{YOUR_SERVICE_NAME_LOWERCASE}:
  coreservice:
    name: YAMBAS
	version: "[3.3,)"
    pathprefix: /yambas/rest
# CORS configuration for your service:
# You can set allowlists of origins (URIs) and HTTP methods for CORS requests.
# E.g.:
# cors-configuration:
#   allowedOrigins:
#     - "http://127.0.0.1:9081"
#     - "https://other.secure.domain"
#   allowedMethods:
#     - GET
#     - HEAD
# For both properties:
# - "*" allows all origins/methods as long as they are valid URIs/HTTP methods, respectively.
# - "none" or an empty value allows NO CORS requests at all.
# - The default is "*".
# cors-configuration:
#   allowedOrigins:
#   allowedMethods:

Service discovery, health checks and load balancing

In a Cloud context, services need to communicate with each other, so they need to be able to find each other. The principle of service discovery is that a single discovery client holds information about all services in the cloud. When a service starts up, it registers itself to the discovery client, with some additional configuration if necessary. When a service wants to communicate with another service, it can retrieve the address from the discovery client.

For service discovery, we are using the Consul discovery client from HashiCorp. An additional useful feature of Consul is health checking: Each service registers itself with an endpoint for health checks, which is queried by Consul to assert the service's healthiness. Please refer to Service health checks for further information.
The picture below describes our discovery use case with the different features provided by Consul:

Another useful principle when working with services is load balancing. Imagine that you start two or more instances of the same services in order to scale your application - how can you make sure that the workload is efficiently distributed between all instances?
Load balancing will solve this for you. We use the default implementation from Spring Cloud, which is also supported by Feign.

The Spring Cloud load balancer includes several implementations to distribute the workload over multiple instances. For more information, you can have a look at the Spring Cloud documentation .

Logging and Debugging

To learn about the logging and debugging features, please refer to Service Logging and Debugging .

Data model classes

When you generate your service, a corresponding Java class will be created for each of your service's classes. This class will contain any attributes that you defined in the Dashboard. As mentioned above, these data model classes will be placed in the package com.apiomat.microservice.<servicename>.model.