Initialise project using the sapi-nt-archetype

You are advised to use the sapi-nt-archetype to generate new projects. A detailed guide on how to do just that can be found here. Once you initialise your project the structure should look like this:

.
├── pom.xml
└── src/
    ├── main/
    |	├── kotlin/
    |	|   └── package/
    |	|       └── SapiNtApplication.kt
    │   └── resources/
    │       ├── application.yaml
    │       ├── documentation/
    │       │   └── documentation.yaml
    │       ├── public/
    │       ├── specs/
    │       ├── templates/
    │       └── vocab/
    │           └── def/
    │               └── base-vocab.ttl
    └── test/
        └── kotlin/
    	    └── package/

Setting up controllers

Using application properties

The application.yaml file generated by sapi-nt-archetype will initially set the sapi-nt.web.controller.default.enabled and sapi-nt.web.controller.doc.enabled properties to true. This will enable the default sapi-nt controllers which handle configured endpoints and documentation. To configure these controllers, read the web configuration documentation.

Custom implementations

On the other hand, if you want more freedom in configuring the controllers you are welcome to implement custom controllers.

Follow this link for more information on how to customise the default controller.

Follow this link for more information on how to customise the documentation controller.

Adding the spec files

The next step is to define endpoints, data sources and views. They should all reside inside the same directory which is by default located under src/main/resources/specs/. You can change the location of the source directory by changing the sapi-nt.config.loadSpecPath configuration property either inside the src/main/resources/application.yaml or using any other spring boot external configuration method found here.

Here is an example of an endpoint spec:

name      : river
type      : item
url       : /river/{__id}
example   : /river/123456
view      : defaultView
pathParameters:
  __id:
    description: id of the test
    type: xsd:integer
    pattern: /([0-9])*/
contentTypes:
  - "application/json"
  - "text/html"
  - "application/geo+json"

Here is an example of an inline view:

name: defaultView
type: view
view :
    - "rdfs:label"
    - "skos:notation"
    - "eg:group"

And here is an example of a data source:

name     : defaultSource
type     : remoteSparqlSource
endpoint : http://environment.data.gov.uk/sparql/bwq/query

To find out more about what attributes can be applied on which type of the spec file then please follow the links bellow:

• Endpoints
• Views
• Data Sources

You can also find spec examples inside the demo application.

Add templates

Endpoints can be annotated with the name of a pebble template to use to render the results as HTML. sapi-nt provides default templates that can all be found here. You can override the default templates by storing your versions in src/main/resources/templates directory using the same names. You can define a new template with the default page structure by extending the layout.peb template. You can do this by writing the pebble expression {% extends "layout" %} at the top of the template.

You can get familiar with all pebble features by reading the documentation.

The pebble environment on endpoint result templates contains the following bindings:

You will also have access to the pebble global variables such as request(HttpServletRequest) and response(HttpServletResponse) objects.

You can customise the pebble engine using the following application properties:

More about application properties can be found here

Setup doctool config

In order to configure the documentation for your project follow the steps detailed in the documentation file.

Running the application

To build your application run

mvn clean package

inside your project directory. Once built you can run the application by running the following command:

java -jar target/${project.name}-${project.version}-SNAPSHOT.jar

where you should substitute ${project.name} with your project’s name and ${project.version} with your project’s version.

Example

Follow this link to find the example application which you can explore to get a better understanding of how things glue together.