Application Configuration

Sapi-nt applications use an application.yaml(or application.properties) Spring configuration file to set up their app-wide settings and core functionality. This file is located in the src/main/resources directory, where it is automatically discovered by Spring. It contains the standard configuration properties for a Spring Boot web application, as well as options that are specific to sapi-nt and any other Spring-based integrations that are included with it.

Your application.yaml is packaged into the JAR when the application is built, so you will need to rebuild the JAR for changes to take effect (your IDE will do this automatically).

Since the application configuration is managed by Spring, you can use standard Spring functionality such as overriding values with command line parameters, and binding values to other properties using the syntax ${property}.

Spring Documentation

• Externalized configuration
• Common application properties

Configuration

The names of the configuration properties are given as dot-separated lists of tokens. When written as a .properties file, these full names are used. When written as .yaml file, this notation denotes a nested tree structure. All of the configuration properties that are specific to sapi-nt are prefixed with the sapi-nt token.

The sapi-nt configs are classified into three broad categories; API, core config and defaults.

API

The API configs, prefixed by the sapi-nt.api token, include the descriptive properties of the API itself, as well as some general configuration options.

Deprecated API Properties

Base URI

You should configure the base URI of your application (sapi-nt.baseURI) to be the URL where the API is located, including the path. This allows your API to function normally regardless of which domain (eg. localhost or a proxy server) it is accessed from. The base URI should use an appropriate domain and path for the data which the API is responsible for exposing. In particular, item endpoints will use this base URI to locate specific resources in the data store.

Context Alias (Proxy)

You should usually only set the sapi-nt.api.contextAlias property if the API is being served by a proxy server. You should set its value to be the path on the proxy server that is identified with the context path of the application (unless the paths are the same, in which case you do not need to set this property). This will ensure that when users view API results in HTML format, the rendered links to other resources will target the correct server-relative path to the resource.

Core Config

The general app-wide configs are prefixed with the sapi-nt.config token.

Web Config

Properties in charge of adding predefined controllers to the application context.

Health Config

Properties in charge of configuring health monitoring components.

When the health monitoring is enabled, i.e. the sapi-nt.health.enabled is set to true, then the HealthController will be added to the context exposing one endpoint:

This endpoint can be utilised by a kubernetes liveness probe if the sapi-nt application is run inside the kubernetes cluster.

Pebble Config

Properties in charge of configuring pebble templating engine

Defaults

You can set defaults, prefixed with sapi-nt.defaults to define default values for certain spec properties.

Spec Defaults

These defaults are applied anywhere that a spec has no value for the corresponding property.

Note

If you have configured a default soft limit for list endpoints in this way, you will not be able to override this with an empty or null soft limit in the usual way. However, you can remove the default soft limit from a list endpoint by setting its softLimit value to -1.

Example

sapi-nt:
  api:
    apiName: Demo App
    apiDescription: >
      This is a sapi-nt Demo Application. It is mainly used to play around with the features so feel free
      to test it and report any bugs.
    baseURI: http://environment.data.gov.uk/test
    comment: This is a test comment
    publisher: Epimorphics
    licenseName: OGL 3
    licenseURI:  http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/
    maxAge: 10000
    defaultItemTemplate: item
    defaultListTemplate: list
  config:
    loadSpecPath: "classpath:endpointSpecs"
    docSpecPath: "classpath:doc"
    checkNonOptionalBindings: false
    enableSpecMonitoring: false
    contextAliases:
      - contextPath: "/static/csv"
        aliases:
          - "file:/home/user/Documents/static/csv/"
  defaults:
    spec:
      endpoint:
        list:
          unionStyle: true
        item:
          isDescribe: false
      property:
        optional: true
        filterable: false

Profiles

You should use your application.yaml file to configure the application as it should be in production. If you are creating a base configuration which will be used by other developers, make sure that you set values which will be compatible with all development environments, for example by using a classpath: prefix when specifying resource locations such as loadSpecPath and docSpecPath.

However, you may need to configure your application specifically for your local environment while developing or testing. You can override any application properties (both sapi-nt and Spring properties) in your local environment by making use of the profiles feature of Spring Boot. This is available by default in all sapi-nt applications.

You can create a profile-specific configuration file named application-{profileName}.yaml or application-{profileName}.properties and run the application with the active Spring profile set to {profileName}. You can do so by setting the Active Profiles field in your run configuration to {profileName}, or by setting the command line flag: --spring.profiles.active={profileName}.

Example

For example, to configure the port on which the server runs in your local environment and enable local spec file monitoring, you could create a file application-developer.yaml with the contents below, and pass the command line flag --spring.profiles.active=developer.

server:
  port: 9898
sapi-nt:
  config:
    loadSpecPath: /my/local/project/src/main/resources/endpointSpecs
    enableSpecMonitoring: true

Note

If you create additional profiles that you wish to use often, make sure to add application-{profileName}.yaml to your .gitignore file so that your profiles do not clash with those of other developers.