NLDI REST (like) Services

Public API

The services are accessed via an http GET request. All navigation output is generated as GeoJSON ("application/vnd.geo+json")

The root is {host}/nldi

Both a test and a production are exposed to the public: https://labs-beta.waterdata.usgs.gov/nldi/linked_data is the test root. https://labs.waterdata.usgs.gov/nldi/linked_data is the production root. This endpoint will give you the valid dataSource names for the other endpoints. There is also a health check at /about/health and version information at /about/info.

Display Up/Down Stream Flow Lines

/{featureSource}/{featureSourceId}/navigate/{navigationMode} where:

{featureSource} identifies the source used to start navigation:
comid start the navigation from an NHDPlus comid
any of the network linked feature sources (listed at /)
{featureSourceId} the NHDPlus comid or feature from which to start the navigation
{navigationMode} is the direction and type of navigation:
DD is __D__ownstream navigation with __D__iversions
DM is __D__ownstream navigation on the __M__ain channel
PP is __P__oint to __P__oint navigation (the stopComid query parameter is required and must be downstream of the {comid})
UM is __U__pstream navigation on the __M__ain channel
UT is __U__pstream navigation including all __T__ributaries

Display Up/Down Stream Events

/{featureSource}/{featureSourceId}/navigate/{navigationMode}/{dataSource} where:

{featureSource} identifies the source used to start navigation (same values as for Flow Lines)
{featureSourceId} the NHDPlus comid or other feature from which to start the navigation
{navigationMode} is the direction and type of navigation (same values as for Flow Lines)
{dataSource} is the abbreviation of the data source from which events should be shown

Query Parameters

Both endpoints accept the same query parameters to further refine/restrict the navigation being requested

distance={dist} limit the navigation to {dist} kilometers from the starting point
stopComid={stopid} for use with PP navigation between the {featureSourceId} and {stopid}
(only applicable to NHDPlus comid navigation and the {stopid} must be downstream of the {featureSourceId})

Development

This is a Spring Batch/Boot project. All of the normal caveats relating to a Spring Batch/Boot application apply. In general, do not run this project via Docker locally, since it places everything under root ownership. Rather, start up the demo db and create an application.yml file as described below, then run the project from your IDE.

Dependencies

This application utilizes a PostgreSQL database. nldi-db contains everything you need to set up a development database environment. It includes data for the Yahara River in Wisconsin.

Running the Demo DB for local development

See the nldi-db project for more details, but in short:

docker network create --subnet=172.26.0.0/16 nldi
docker run -it --env-file ./.env -p 127.0.0.1:5437:5432/tcp usgswma/nldi-db:demo

Note the 5437 port mapping, which is used in the environmental variables below.

Environment variables

To run the project (connecting to a separately running db instance) you will need to create the file application.yml in the project's root directory and add the following (normal defaults are filled in):

nldiDbHost: localhost
nldiDbPort: 5437 #Or whatever port you map it to
nldiDbUsername: [dbUserName] #See nldi-db project .env file 'NLDI_READ_ONLY_USERNAME'
nldiDbPassword: [dbPassword] #See nldi-db project .env file 'NLDI_READ_ONLY_PASSWORD'
nldiDbName: [dbName] #See nldi-db project .env file 'NLDI_DATABASE_NAME'
nldiProtocol: http
nldiHost: owi-test.usgs.gov:8080
nldiPath: /test-url

serverContextPath: /nldi
springFrameworkLogLevel: INFO
serverPort: 8080

spring.security.user.password: changeMe

Testing

This project contains JUnit tests. Maven can be used to run them (in addition to the capabilities of your IDE).

To run the unit tests of the application use:

mvn package

To additionally start up a Docker database and run the integration tests of the application use:

mvn verify -DTESTING_DATABASE_PORT=5445 -DTESTING_DATABASE_ADDRESS=localhost -DTESTING_DATABASE_NETWORK=nldi

ee-usgs/nldi-services