brazil-data-cube/lccs-ws-spec

Land Cover Classification System Web Service Specification

Land Cover Classification System Web Service - Specification

About

Currently, there are several data sets on regional, national and global scales with information on land use and land cover that aim to support a large number of applications, including the management of natural resources, climate change and its impacts, and biodiversity conservation. These data products are generated using different approaches and methodologies, which present information about different classes of the earth's surface, such as forests, agricultural plantations, among others. Initiatives that generate land use and land cover maps normally develop their own classification system, with different nomenclatures and meanings of the classes used.

In this context, the LCCS-WS (Land Cover Classification System Web Service) aims to provide a simple interface to access the various classification systems in use and their respective classes. Therefore, this service proposes a representation for the classification systems and provides an API to access the classes and their symbolizations. It is also possible to stablish mappings between classes of different systems.

Free and Open Source implementations based on this service can be found in the lccs-ws (server) and lccs.py (Python client). See also the service Web Land Trajectory System (WLTS), which uses LCCS-WS to represent the classes associated with the features retrieved in its queries.

Repository Organization

• api: LCCS Specification using OpenAPI 3.0.
• jsonschemas: JSON Schema for the classification systems and classes.

Overview of Service Operations

• The /classification_systems operation when queried with a GET method returns the list of land use and cover classification systems available in the service. A POST request on this route allow the client to add a new classification system.
• The /classification_systems/{system_id_or_identifier} operation when queried with a GET method returns a document with full information about the classification system.
• The /classification_systems/{system_id_or_identifier}/classes operation when queried with a GET method returns the list of classes from a classification system.
• The /classification_systems/{system_id_or_identifier}/classes/{class_id} operation when queried with a GET method returns information about a class from a classification system
• The /classification_systems/{system_id_or_identifier}/styles operation when queried with a GET method returns the list of styles of the classification.
• The /classification_system/{system_id_or_identifier}/styles/{style_id} operation when queried with a GET method returns a document with the style of the classification system.
• The /mappings/{system_id_or_identifier_source} operation when queried with a GET method returns a list of available mappings for the classification system.
• The /mappings/{system_id_or_identifier_source}/{system_id_or_identifier_target}: operation when queried with a GET method returns the mapping between the classification systems. A POST request on this route allow the client to add a new mapping.

Building the Documentation

Requirements

The build system for the REST API documentation relies on the Node.js run-time environment:

• Node.js (Version 8+).
• ReDoc: generates HTML reference documentation from an OpenAPI specification file.

Build

If you have Node.js installed, please, execute the following command to install the ReDoc dependency:

$ npm install

After that, generate the documentation:

$ npm run build

The above command will create a folder named dist with the bundled file index.html. You may open it in your web browser or may serve it with an HTTP Server.

For Python developers, you can serve the HTML with:

python3.7 -m http.server 8080 --directory dist

License

Copyright (C) 2019-2021 INPE.

Land Cover Classification System Web Service is free software; you can redistribute it and/or modify it under the terms of the MIT License; see LICENSE file for more details.

lccs-ws-spec's Issues

Improve documentation

• In the README.rst, add a new section named Overview of Service Operations before the section Building the Documentation. Example:
  • /classification_systems: The /classification_systems operation when queried with a GET method returns the list of land use and cover classification systems available in the service. A POST request on this route allow the client to add a new classification system. Example: http://localhost/lccs/classification_systems.

system_id as int in getClassificationSystems

system_id could be a combination of name and version of the classification system for improved readability

Add README.rst

Add the JSON Schema needed response validations

Verify if it is possible to set LinkType schema as an enumeration

add operation that retrieves the identifier given a name

• In classification systems use name and version.
• In classes and style formats, just the name.

Review the OpenAPI definition

• /classification_systems: the post method could receive a full classification system (with all classes, styles and mappings).

• /classification_systems/{system_id}: the response document should be based on links for its parts.

• Homogenize the use of links in the service.

Revision in the OpenAPI 3 spec - Add CRUD operations

Translate README.rst for English

Revision in the OpenAPI 3 spec

Include the service specification for version 0.2.0 using OpenAPI 3

Release version 0.2.0

Tasks:

• Inform the right version in JSONSchemas, OpenAPI definitions and package.json.
• Review the CHANGES.rst.
• Create a branch named: b-0.2.
• Review links in the documentation for the stable version (README.rst).
• From the branch b-0.2, create a tag named: v0.2.0.
• In the master branch increase version in JSONSchemas, OpenAPI definitions and package.json.
• Notify to the community the release of a new version.

Look for a tool that can generate JSONSchemas from YAML OpenAPI definitions