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
See also curl
documentation.
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 filesdiagnostics
- 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.
Troubleshooting
See also the log files.