Appbase configuration

A sapi application normally uses the appbase machinery for configuration. The web.xml sets up the core machinery and specifies how the appbase configuration is found.

Web.xml

A default web.xml configuration is shown below.

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

  <display-name>Data API</display-name>

  <listener>
    <listener-class>com.epimorphics.appbase.core.AppConfig</listener-class>
  </listener>

  <filter>
    <filter-name>CORS</filter-name>
    <filter-class>com.epimorphics.appbase.webapi.CorsFilter</filter-class>
  </filter>
  <filter-mapping>
    <filter-name>CORS</filter-name>
    <url-pattern>/*</url-pattern>
  </filter-mapping>

  <filter>
    <filter-name>extension-filter</filter-name>
    <filter-class>com.epimorphics.appbase.webapi.ExtensionFilter</filter-class>
    <init-param>
      <param-name>html</param-name>
      <param-value>text/html</param-value>
    </init-param>
    <init-param>
      <param-name>ttl</param-name>
      <param-value>text/turtle</param-value>
    </init-param>
    <init-param>
      <param-name>rdf</param-name>
      <param-value>application/rdf+xml</param-value>
    </init-param>
    <init-param>
      <param-name>jsonld</param-name>
      <param-value>application/ld+json</param-value>
    </init-param>
    <init-param>
      <param-name>json</param-name>
      <param-value>application/json</param-value>
    </init-param>
    <init-param>
      <param-name>csv</param-name>
      <param-value>text/csv</param-value>
    </init-param>
  </filter>
  
  <filter-mapping>
    <filter-name>extension-filter</filter-name>
    <url-pattern>/*</url-pattern>
  </filter-mapping>
  
  <filter>
    <filter-name>VelocityFilter</filter-name>
    <filter-class>com.epimorphics.appbase.webapi.VelocityFilter</filter-class>
  </filter>
  
  <filter>
    <filter-name>LogRequestFilter</filter-name>
    <filter-class>com.epimorphics.simpleAPI.webapi.LogRequestFilter</filter-class>
  </filter>

  <filter-mapping>
    <filter-name>LogRequestFilter</filter-name>
    <url-pattern>/*</url-pattern>
  </filter-mapping>

  <filter-mapping>
    <filter-name>VelocityFilter</filter-name>
    <url-pattern>/ui/*</url-pattern>
  </filter-mapping>

  <filter>
    <filter-name>Jersey Web Application</filter-name>
    <filter-class>org.glassfish.jersey.servlet.ServletContainer</filter-class>
    <init-param>
      <param-name>jersey.config.server.provider.packages</param-name>
      <param-value>com.epimorphics.webapi,com.epimorphics.server.webapi,com.epimorphics.simpleAPI.webapi,com.epimorphics.EArealtime.webapi</param-value>
    </init-param>
    <init-param>
      <param-name>jersey.config.servlet.filter.forwardOn404</param-name>
      <param-value>true</param-value>
    </init-param>
  </filter>
  
  <filter-mapping>
    <filter-name>Jersey Web Application</filter-name>
    <url-pattern>/*</url-pattern>
  </filter-mapping>
 
  <welcome-file-list>
    <welcome-file>ui/index.html</welcome-file>
  </welcome-file-list>
  
  <context-param>
    <param-name>AppConfig.app</param-name>
    <!-- Will initialize from first of these it finds -->
    <param-value>/etc/api/app.conf,/opt/api/conf/app.conf,{webapp}/WEB-INF/app.conf</param-value>
  </context-param>  

</web-app>

The filters for request logging, extension typing, CORS and velocity are all optional but generally useful to have.

The AppConfig.app param gives a search path for locating the appbase configuration file. It's generally useful to have some external locations first then a fall back on something internal to the war. That way you can package a war that's usable out of the box but which can be configured externally.

Example app.conf

For the app.conf file itself then a typical set up is:

# Plugin extension for velocity library, optional
apix                 = com.epimorphics.simpleAPI.webapi.LibAPI

# Velocity engine
velocity             = com.epimorphics.appbase.templates.VelocityRender
velocity.templates   = {webapp}/WEB-INF/templates
velocity.root        = /ui
velocity.production  = true

# Default prefixes
prefixes = com.epimorphics.appbase.core.PrefixService
prefixes.prefixFile    = {webapp}/WEB-INF/prefixes.ttl

# Data source low level
ssource              = com.epimorphics.appbase.data.impl.RemoteSparqlSource
ssource.endpoint     = http://localhost:3030/ds/query

# Wrap low level source in sapi adapater
dsource              = com.epimorphics.simpleAPI.query.impl.SparqlDataSource
dsource.source       = $ssource

# API configuration
api                  = com.epimorphics.simpleAPI.core.API
api.source           = $dsource
api.baseURI          = http://environment.data.gov.uk/flood-monitoring/
api.documentation    = http://environment.data.gov.uk/flood-monitoring/doc/reference
api.publisher        = Environment Agency
api.licence          = http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/
api.contextURL       = http://environment.data.gov.uk/flood-monitoring/meta/context.jsonld
api.comment          = Status: Beta service
api.endpointSpecDir  = {webapp}/WEB-INF/endpointSpecs
api.maxAge           = 300
api.version          = 0.7

The prefix service allows you to define a default set of prefixes that can be used in endpoint/view specifications without having to locally declare them for each endpoint.

The API object takes a large (and growing) collection of configuration parameters to adapt the API behaviour.

Configuration options

Generic config extensions

Geo and text search