NovaStar Program Reference / Web / REST Web Services

Overview

NovaStar provides data access via REST web services. TriLynx Systems is phasing in the use of web services as an alternative to legacy data access provided by the Administrator Interface. Web services allow data access to occur without using the Administrator Interface, which is intended for flood warning system administration.

TODO smalers 2017-08-07 need to include link to web services API.

Command Line Usage

Web services can be accessed on the command line using the curl program.

curl URL -o outputFile

Examples

Proactively Create Cached Versions of Web Service Resources to Improve System Performance

Some NovaStar components, such as the Operator Interface, query the web services to retrieve resources that are resource-intensive to create. In these cases, it is desirable to minimize user wait time. In order to achieve this result it is necessary to balance the need for timely data with the reality that some processes take longer to create data resources. In particular, the stationSummaries web service request, when processing the entire system, typically requires 10 or more seconds to complete. If many Operator Interface users access the same resource in a short time, and the Operator Interface performs five minute updates, then the NovaStar server performance will suffer. To address this issue, the web service can cache resources, as follows:

Operator Interface performs stationSummaries?forOperatorSummaryTable=true query every 5 minutes.
- If a cached version is available that has not expired, it is immediately returned.
- If it is necessary to query the database and create the summary, the result is automatically cached with a default expiration of 120 seconds. This provides some optimization in cases where the proactive cache process is not configured, but may have little effect in this case because the expiration is 120 seconds and will be aged out by the next time the Operator Interface does its 5 minute update.
A scheduled process should be run to proactively generate cached resources, so that the Operator Interface never needs to wait. This product will be slightly aged. To achieve appropriate balance, the scheduled process should run in an interval shorter than 5 minutes but with enough spacing to allow the cache generation to complete before the next iteration.

The following scheduled processes are recommended to be run every 2 minutes (pending field testing to determine appropriate frequency). Note that curl only needs to request the resource but the web services application handles saving the file.

curl http://novastar-server/data/api/v1/stationSummaries?forOperatorStationSummary=true&cache=true&cacheExpiration=120
curl http://novastar-server/data/api/v1/stationSummaries?forOperatorStationSummary=true&cache=true&cacheExpiration=120&format=geojson

The first resource is used by the station summary. The second is used for the map display.

TODO smalers 2017-08-08 need to enable key with the above to ensure that only back end process is controlling the cache.

A two minute cycle time would correspond to a two-minute ALERT2 TDMA frame. The appropriate time should be evaluated based on data collection timing and server performance.

The current cache can be checked by accessing the cache web service resource in a web browser.

Administrator Interface

TODO smalers 2017-08-07 need a screenshot showing scheduler example

Log File Location

TODO smalers 2017-08-07 need Thaddeus to insert location in the operational system reflecting rolling logs.

Performance Considerations

It is important that web services perform well so that calling programs perform well. System performance can be evaluated by using the following web service calls:

cache - displays current cached files
diagnostics - displays server memory use

Currently only the stationSummaries resource is cached. Other resources could be cached similarly, although caching requires disk space and/or memory for the cached copies. Performance will be evaluated as web services are phased in.

If necessary, additional resources can be cached and additional software tuning can be implemented.