Configuration

This document covers the following topics:

General Configuration

The following configurations have to be done before running the Natural OpenAPI server.

In the application.properties file, define the following properties:

Parameter Description Default Value
com.softwareag.natural.openapi.server.config.host.address The IP address of the Natural Subprogram Server. localhost
com.softwareag.natural.openapi.server.config.host.port The port to connect to the Natural Subprogram Server. 2025
natural.integration.services.files A list of JSON files that should be accessible by the Natural OpenAPI Server (full file names separated with comma. For examples, /opt/softwareag/NaturalOpenAPIServer/services/file1.json, /opt/softwareag/NaturalOpenAPIServer/services/file2.json). none
natural.integration.services.directory The location of folder that contains all the service definition files. ./services
com.softwareag.natural.openapi.server.config.host.ssl.enabled Define whether to use SSL or not. false
com.softwareag.natural.openapi.server.config.host.ssl.certsChain[0] Location of the public certificate files to connect to Natural Subprogram Server using SSL communication. none
com.softwareag.natural.openapi.web.config.authenticationType The Authentication used to connect to Natural Subprogram Server. none
com.softwareag.natural.openapi.web.config.oAuth2Config.tokenUrl The token URL of the credentials provider to get the Bearer token when testing with the Swagger UI web client. none
com.softwareag.natural.openapi.web.config.oAuth2Config.scopes The scopes to request from the credentials provider in the Bearer token when testing with the Swagger UI web client. api.read="Read API access", api.write="Write API access", api.get="Get API access"
com.softwareag.natural.openapi.server.config.host.charset The charset to use when encoding the requests to the Natural Subprogram Server. ISO-8859-15
management.endpoints.web.exposure.include This parameter controls the exposure of the reload service endpoint. If not defined, this property must be added with the value reloadServices. If already defined, append reloadServices to the existing comma-separated values. none

Notes:

  1. You can define a file list in the natural.integration.services.files property and define another folder in the natural.integration.services.directory property. The application will use the resources from both locations.
  2. All the JSON files created by the Natural OpenAPI Eclipse Plug-In should be copied to the service folder (defined in the application.properties file by the natural.integration.services.directory property, or they should be defined in the natural.integration.services.files property).

Natural Error to HTTP Mapping

The Natural OpenAPI Server can map backend Natural error codes to HTTP status codes.

The mapping resolution order is:

  1. Exact match (for example, NAT3009)

  2. Matching numeric range (for example, 0..99)

  3. Global default mapping

Default mappings are predefined in the Natural OpenAPI Server.

You can override or extend mappings in the application.properties file using the error-mapping.* prefix.

Example: Override one Natural specific code

error-mapping.sources.natural.specific.NAT3009.http-code=422
error-mapping.sources.natural.specific.NAT3009.http-message=Unprocessable Entity
error-mapping.sources.natural.specific.NAT3009.category=VALIDATION_ERROR
error-mapping.sources.natural.specific.NAT3009.log-level=WARN

Example: Define a Natural range mapping

error-mapping.sources.natural.ranges.syntax.from=0
error-mapping.sources.natural.ranges.syntax.to=49
error-mapping.sources.natural.ranges.syntax.http-code=400
error-mapping.sources.natural.ranges.syntax.http-message=Bad Request
error-mapping.sources.natural.ranges.syntax.category=SYNTAX_ERROR
error-mapping.sources.natural.ranges.syntax.log-level=WARN

Example: Override global fallback

error-mapping.default-mapping.http-code=500
error-mapping.default-mapping.http-message=Internal Server Error
error-mapping.default-mapping.category=SYSTEM_ERROR
error-mapping.default-mapping.log-level=ERROR

In addition to Natural code mappings, transport failures are mapped by the WebFlux error handler:

  • Backend connection failure: 502 Bad Gateway

  • Backend timeout: 504 Gateway Timeout

  • Unknown/unmapped errors: 500 Internal Server Error

On this page