sat-api-browser

A query constructor and results visualizer for stac-spec compliant APIs. See sat-api-browser for a test instance leveraging the sat-api.

Intent

The STAC api-spec provides querying and filtering capabilities for data represented as STAC catalogs. The sat-api-browser's intent is to simplify STAC compliant API filter construction and results visualization by providing a UI which lets users use STAC extension schemas to build and validate filters.

Once the user has received the results of the query, they can select interesting candidate items and save them to a 'shopping cart' of datasets (represented as STAC items) that they can leverage in other applications (via STAC catalog or the mosaicjson-spec). This provides the ability to search for data in a more organic and iterative fashion (much like shopping) rather than attempting to build a single all encompassing query to capture appropriate results like traditional data search applications.

This project was initiated by @sharkinsspatial as part of Development Seed's wider work in building the sat-api and open sourced to to the community to help drive contributions and new functionality. New contributions are welcomed and you can contact @sharkinsspatial or [email protected] for additional support or assistance with customization.

Build, Run, Deploy, and Test

Install Dependencies

Install the necessary dependencies with:

yarn install

Build Configuration

The following environment variables are required. You can copy and rename .env.sample to .env for use as a template.

• SKIP_PREFLIGHT_CHECK
  skip preflight check for yarn
• REACT_APP_API_URL The URL with port of the stac compliant api. This should not include the /stac path prefix.
• REACT_APP_MAPBOX_ACCESS_TOKEN A token for accessing the Mapbox API
• REACT_APP_RESULT_LIMIT Maximum number of results the API will display

Example:

SKIP_PREFLIGHT_CHECK=true
REACT_APP_API_URL=https://stac.boundlessgeo.io
REACT_APP_MAPBOX_ACCESS_TOKEN=px.eyJ1IjoicGhpbHZhcm6lciIsImEiOiJjanhhbHlnZHkweWtoM3hucmp3NTZsbmpsIn0.Njnnayl6FxkecPBZvKWfzB
REACT_APP_RESULT_LIMIT=20

Build and Run Locally

To run the application locally, run the following from the project directory:

yarn start

The app will run in the development mode. Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits. You will also see any lint errors in the console.

Build Deployable Artifacts

yarn run build

Builds the app for production to the build folder.
It correctly bundles React in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes.
Your app is ready to be deployed!

Deploy to S3

yarn run build && aws s3 sync build/ s3://sat-api-browser-dev

Build and deploy to S3 bucket.

Tests

To run the tap-based unit tests:

yarn test

Design Approach

The application uses Redux for state management.

The Redux store is a vanilla JS object but each logical state slice is an ImmutableJS map.

State slices are never queried directly from the store but are accessed via selectors which are memomized using the Reselect library where appropriate.

The application design uses both Presentational and Container components but makes liberal use of react-redux connect as outlined here.

State that is transient or does not affect other components in the application can be maintained directly in components where appropriate as described here.

Pure stateless React components are preferred but Class components are used where local state is required.

Any impure actions which may have side effects (asynchronous API requests, interaction with browser local storage) are isolated in Redux middleware.

Cross-cutting actions are also managed through the use of middleware.

The application uses Mapbox GL JS for map display and management. When the Map React component mounts it loads a style and some GeoJSON data. This state is then pushed into the Redux store where all subsequent actions act on this state and provide the Map component with the new updated style via props. A more detailed description of this approach is available in this blog post by Tom Macwright.

The application uses Material-UI for UI components and styling.

Individual component style overrides are acheived using Material UIs own css injection with JSS.

The application store is configured to support the redux-devtools-extension for advanced debugging with state rewind and fast forward.

Because the application makes extensive use of HOCs, wrapped components are exposed as the default export while raw components are available as a named component. This allows for unit testing without invoking HOC behavior.

The application uses tape-await to simplify asynchronous test flow for middleware.