Spec Configuration

Sapi-nt uses a set of user-defined specification, or spec, files to configure the API and its underlying resources. Without spec files, a sapi-nt application can run, but it will not expose a useful API. These files are written in YAML format, and may contain more than one YAML document per file.

In their serialized form, specs are characterised by their type field, which is required in order to identify which type of entity they should be deserialized to. They must also have a name field which uniquely identifies them.

Similarly to the application configuration, you can bind property values in your specs to environment variables and application properties using the syntax ${property}.

Spec Types

These are the types of spec file that you can define and the documentation pages for each:

• Data Source
  • File
  • Classpath
  • Remote
• Model
• Endpoint
  • Item
  • List
  • Template
  • Forward
• View
• Request Validator
  • Required Parameter
  • Parameter Pattern

To create a fully functional API, you will need to define at least one data source, model and endpoint.

Location

Spec files are located in a directory determined by the sapi-nt.config.loadSpecPath application property. In production, this should usually be a classpath location under src/main/resources, however for development and testing it may be convenient to use a local file location. All spec files for the application must be in that directory.

If your sapi-nt.config.loadSpecPath value is a classpath location (ie. using the classpath: prefix), then sapi-nt will attempt to find spec files that have been packaged in the application JAR. As a result, you must rebuild the JAR for changes to take effect. However, if the path is configured to be a local file location, you will not need to rebuild for changes to take effect.

Monitoring

You can enable live monitoring of spec files by setting the sapi-nt.config.enableSpecMonitoring application property to true. If you do, sapi-nt will monitor the local file system for changes to specs and update the application configuration accordingly. The responsiveness of this feature may depend on your operating system.

Note

Since this feature monitors the local file system, it will only be enabled if your loadSpecPath is a local file path.

Quick Reference

The table below contains a quick reference to all spec types and their meanings. Some specs also have a short form type that can be used interchangeably with the long hierarchical type.