Thin Web binding API to access timeseries data.
Clone or download
Pull request Compare This branch is 14 commits ahead, 24 commits behind 52North:develop.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.travis
etc
io
rest
spi
src/main/assembly
web-resources
.gitignore
.travis.yml
CHANGELOG.md
LICENSE
NOTICE
README.md
pom.xml

README.md

52n Series REST API

series-rest-api architecture overview

Description

Thin Web binding API to access timeseries data.

The Series REST API provides an access layer to sensor data via RESTful Web binding with different output formats like json, pdf or png. It provides a well defined Sevice Provider Interface (SPI) which can be implemented by arbitrary backend services to make series data available via the API

The Series REST API provides a thin access layer to sensor and observation data via RESTful Web binding. In addition, it offers several IO functionalities e.g.

  • prerendering of series data,
  • generalization,
  • overlaying of data from multiple series
  • conversion of raw data to other formats like pdf and png

Output formats for stationary, mobile, insitu and remote sensors are available, each filterable by metadata parameters. This enables clients to access the data via different approaches, e.g. to filter all series by phenomena first or by a special procedure.

Next to the Web API, a Service Provider Interface (SPI) defines the underlying interface for data providing backends. With this, the API is flexible enough to be put ontop of arbitrary data stores. Its modular design enables a seamless integration into existing Web applications.

The following main frameworks are used to provide this API:

Existing SPI implementations:

References

License

The client is published under the GNU General Public License v2 (GPLv2).

Changelog

Contributing

We try to follow the GitFlow model, although we do not see it that strict.

However, make sure to do pull requests for features, hotfixes, etc. by making use of GitFlow. Altlassian provides [a good overview] (https://www.atlassian.com/de/git/workflows#!workflow-gitflow). of the most common workflows.

Contact

Henning Bredel (h.bredel@52north.org)

Quick Start

Client development

The Web API documentation gives a detailed overview on how to access the data provided by the API. Available I/O functions are described there, too, like generelization, chart rendering/overlay, etc.

The API documentation is in the 52°North wiki: https://wiki.52north.org/bin/view/SensorWeb/SensorWebClientRESTInterface

API Configuration

How to provide a custom SPI implementation is beyond this section. See (...TBD...) to get detailed information on this.

Logging

Generalizer

In file WEB-INF/classes/config-general.json add

"generalizer": {
    "defaultGeneralizer": "lttb",
    "noDataGapThreshold": 5
}

The parameters are described on the official Web API documentation.

Prerendering

Prerendering is supported for measurement data.

Prerendering configuration is a task which can be run regularly by a scheduler. Configuration is done as a PreRenderingJob bean. Checkout WEB-INF/spring/spi-impl-dao_tasks.xml how to set up a prerendering job. The actual rendering configuration for each series/phenomenon can be referenced within the job bean.

Rendering configuration tells how to render the actual series information. It comprises a phenomenonStyles section (valid for a set of series for a given phenomenon) and a seriesStyles section (which actually overrides a phenomenon style of a specific series) Each section can override parameters made in the generalConfig.

Only those series are prerendered having a match either in phenomenonStyles or seriesStyles.

Date formatting

In file WEB-INF/spring/config-general.json you can set timeformat Parameter. Please checkout the Java SimpleDateFormat rules how the format has to look like.

Rendering Hints

TBD

Status Intervals

TBD

Metadata from a Database

TBD

Credits

The development of the 52°North REST-API implementation was supported by several organizations and projects. Among other we would like to thank the following organisations and project

Project/Logo Description
BMBFCOLABIS - Collaborative Early Warning Information Systems for Urban Infrastructures The development of this version of the 52°North SOS was supported by the German Federal Ministry of Education and Research research project COLABIS (co-funded by the German Federal Ministry of Education and Research, programme Geotechnologien, under grant agreement no. 03G0852A)
NeXOS - Next generation, Cost-effective, Compact, Multifunctional Web Enabled Ocean Sensor Systems Empowering Marine, Maritime and Fisheries Management The development of this version of the 52°North REST-API was supported by the European FP7 research project NeXOS (co-funded by the European Commission under the grant agreement n°614102)
FixO3 - Fixed-Point Open Ocean Observatories The development of this version of the 52°North REST-API was supported by the European FP7 research project FixO3 (co-funded by the European Commission under the grant agreement n°312463)
ODIP II - Ocean Data Interoperability Platform The development of this version of the 52°North REST-API was supported by the Horizon 2020 research project ODIP II (co-funded by the European Commission under the grant agreement n°654310)
SeaDataCloud The development of this version of the 52°North REST-API was supported by the Horizon 2020 research project SeaDataCloud (co-funded by the European Commission under the grant agreement n°730960)
Wupperverband The Wupperverband for water, humans and the environment (Germany)
Belgian Interregional Environment Agency (IRCEL - CELINE) The Belgian Interregional Environment Agency (IRCEL - CELINE) is active in the domain of air quality (modelling, forecasts, informing the public on the state of their air quality, e-reporting to the EU under the air quality directives, participating in scientific research on air quality, etc.). IRCEL — CELINE is a permanent cooperation between three regional environment agencies: Agence wallonne de l'Air et du Climat (AWAC), Bruxelles Environnement - Leefmilieu Brussel and Vlaamse Milieumaatschappij (VMM).
GEOWOW - GEOSS interoperability for Weather, Ocean and Water The development of this version of the 52°North SOS was supported by the European FP7 research project GEOWOW (co-funded by the European Commission under the grant agreement n°282915)