Feature Manager REST API

Overview

Feature management microservice is a data repository in GeoJSON format.

Feature Management reponsabilities:

• Extract data references thanks to [IFeatureFactoryPlugins],
• Create, patch or delete data references,
• Re-notify stakeholders of existing data references,
• Delegate the storage of files (if any) to Storage Management.

To edit this repository, a data producer has to send requests.

At the moment, 2 API are available :

• Messaging API (AMQP) allows to publish creation, reference, patch, deletion and notification requests on specific exchanges.
• HTTP REST API allows to submit creation requests (as POST HTTP requests), update requests (as PATCH HTTP requests) or deletion requests (as DELETE HTTP requests).

Under the hood, those reponsabilities are divided between two modules: featureprovider and feature. featureprovider is only responsible for handling data references extraction requests, that is extraction of information needed from physical files to create a data reference that is then handled by the feature module.

API are documented in detail below.

Request payload

Regardless of the API used, payload of each API is expected in GeoJSON format.

The basic structure is as follows :

• A required id,
• A required type with value Feature,
• An optional geometry in GeoJSON format,
• An optional set of properties.

{
    "id": "FeatureId",
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [
            125.6,
            10.1
        ]
    },
    "properties": {
        "name": "Dinagat Islands"
    }
}

For the purposes of this microservice, GeoJSON structure is extended with following properties :

• An urn (uniform resource name as unique identifier) generated by the microservice when creating a new reference and expected only when updating a reference.
• A required model representing the name of the model defining the expected properties field structure (and previously configured).
• A required entityType defining the reference business type.
• An optional files property with a fixed structure that allows to store or reference physical data (service delegated to another microservice called Storage Management).

{
    "id": "FeatureId",
    "urn": "UniqueFeatureId",
    "model": "RelatedModelName",
    "entityType": "DATA",
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [
            125.6,
            10.1
        ]
    },
    "properties": {
        "name": "Dinagat Islands"
    },
    "files": [
        {
            "locations": [
                {
                    "storage": "DISK",
                    "url": "file://home/user/regards/file.zip"
                }
            ],
            "attributes": {
                "dataType": "RAWDATA",
                "mimeType": "application/zip",
                "filename": "file.zip",
                "filesize": "8013",
                "algorithm": "MD5",
                "checksum": "4e188bd8a6288164c25c3728ce394927"
            }
        }
    ]
}

Payload detailed properties

Feature

Path	Type	Description	Optional
id	String	Id from provider
urn	String	Unique feature identifer based on provider identifier with TEST:REQUEST:2342

danger

Urn is only expected in update and deletion requests!

Files

Path	Type	Description	Optional
locations[].storage	String	Storage	true
locations[].url	String	Url location
attributes.dataType	String	RAWDATA, QUICKLOOK_SD, QUICKLOOK_MD, QUICKLOOK_HD, DOCUMENT, THUMBNAIL, DESCRIPTION
attributes.mimeType	String	MIME type
attributes.filename	String	Filename
attributes.filesize	Number	File size	true
attributes.algorithm	String	Checksum algorithm	true
attributes.checksum	String	Checksum	true

danger

Algorithm & cheksum are required if data have to be stored by Storage Management.

Request metadata

As the payload, regardless of the API used, metadata is often associated with a request.

Metadata detailed properties

Path	Type	Description	Optional
metadata.override	Boolean	Indicate wether the previous version should be deleted	true
metadata.session	String	Arbitrary session name to classify data for human operators
metadata.sessionOwner	String	Arbitrary session owner to classify data for human operators
metadata.storages	Array	Target storages if there are files to store (may be empty!)	true
metadata.storages[].pluginBusinessId	String	Storage plugin identifier (previously configured in Storage Management
metadata.storages[].targetTypes	Array	List of data object types accepted by this storage location	true
metadata.storages[].storePath	String	Directory in which to store the file	true
metadata.priority	String	HIGH, NORMAL, LOW

danger

override should only be specified with Extraction or Creation requests.

REST API

For creation and update requests, REST API is expected a GeoJSON collection extended with specific metadata.

The structure is as follows :

• Required metadata that apply to all features,
• A required type with value FeatureCollection,
• Required features containing a set of GeoJson feature.

Example of feature creation collection:

{
    "metadata": {
        "session": "session",
        "sessionOwner": "owner",
        "storages": [
            {
                "pluginBusinessId": "disk"
            }
        ],
        "priority": "NORMAL"
    },
    "requestOwner": "owner",
    "features": [{}, {}, {}],
    "type": "FeatureCollection"
}

Example of feature update collection:

{
    "metadata": {
        "storages": [
            {
                "pluginBusinessId": "disk"
            }
        ],
        "priority": "NORMAL"
    },
    "features": [{}, {}, {}],
    "type": "FeatureCollection"
}

danger

Session & session owner are not supported in update metadata!

Feature Creation request example

Request

URL

/features

URL template

/features

Method

POST

Headers

Authorization:Bearer{token}
Content-Type:application/geo+json;charset=UTF-8

Data params

{
  "requestOwner" : "test",
  "metadata" : {
    "sessionOwner" : "owner",
    "session" : "session",
    "storages" : [ {
      "pluginBusinessId" : "disk"
    } ],
    "priority" : "NORMAL"
  },
  "features" : [ {
    "urn" : null,
    "entityType" : "DATA",
    "model" : "FEATURE01",
    "history" : {
      "createdBy" : "owner",
      "updatedBy" : null,
      "deletedBy" : null
    },
    "files" : [ {
      "locations" : [ {
        "storage" : null,
        "url" : "http://www.test.com/filename.xml"
      } ],
      "attributes" : {
        "dataType" : "RAWDATA",
        "mimeType" : "application/xml",
        "filename" : "filename",
        "filesize" : 100,
        "algorithm" : "MD5",
        "checksum" : "checksum"
      }
    } ],
    "last" : false,
    "id" : "MyId",
    "geometry" : {
      "coordinates" : [ 10.0, 20.0 ],
      "type" : "Point",
      "bbox" : null,
      "crs" : null
    },
    "normalizedGeometry" : null,
    "properties" : {
      "data_type" : "TYPE01",
      "file_characterization" : {
        "valid" : true
      }
    },
    "type" : "Feature"
  } ],
  "type" : "FeatureCollection"
}

Response

• Code: 201 Created

Headers:

X-Content-Type-Options:nosniff
X-XSS-Protection:1; mode=block
Cache-Control:no-cache, no-store, max-age=0, must-revalidate
Pragma:no-cache
Expires:0
X-Frame-Options:DENY
Access-Control-Allow-Origin:*
Access-Control-Allow-Methods:POST, PUT, GET, OPTIONS, DELETE
Access-Control-Allow-Headers:authorization, content-type, scope
Access-Control-Max-Age:3600
Content-Type:application/hal+json

Content:

    
{
  "granted" : {
    "MyId" : "d1b873d8-caeb-4380-b822-8728ec97ee73"
  },
  "denied" : {
    "empty" : true
  },
  "messages" : [ ]
}

API return maps of granted and denied requests :

• Granted property maps feature id to its related request id and allows the producer to optionnaly monitor request lifecycle listening to request event.
• Denied property maps feature id to a list of rejection causes.

Feature Patch request example

Request

URL

/features

URL template

/features

Method

PATCH

Headers

Authorization:Bearer{token}
Content-Type:application/geo+json;charset=UTF-8

Data params

{
  "requestOwner" : "test",
  "metadata" : {
    "storages" : [ ],
    "priority" : "NORMAL"
  },
  "features" : [ {
    "urn" : "URN:FEATURE:DATA:tenant:ca4015e5-9c59-49ff-b35e-f30c6929f402:V1",
    "entityType" : "DATA",
    "model" : "FEATURE01",
    "history" : {
      "createdBy" : "owner",
      "updatedBy" : null,
      "deletedBy" : null
    },
    "files" : [ ],
    "last" : false,
    "id" : "MyId",
    "geometry" : null,
    "normalizedGeometry" : null,
    "properties" : {
      "file_characterization" : {
        "invalidation_date" : "2021-09-16T20:06:25.906Z",
        "valid" : false
      }
    },
    "type" : "Feature"
  } ],
  "type" : "FeatureCollection"
}

Response

• Code: 201 Created

Headers:

X-Content-Type-Options:nosniff
X-XSS-Protection:1; mode=block
Cache-Control:no-cache, no-store, max-age=0, must-revalidate
Pragma:no-cache
Expires:0
X-Frame-Options:DENY
Access-Control-Allow-Origin:*
Access-Control-Allow-Methods:POST, PUT, GET, OPTIONS, DELETE
Access-Control-Allow-Headers:authorization, content-type, scope
Access-Control-Max-Age:3600
Content-Type:application/hal+json

Content:

    
{
  "granted" : {
    "URN:FEATURE:DATA:tenant:ca4015e5-9c59-49ff-b35e-f30c6929f402:V1" : "65726bf9-a039-4f34-a6d2-620a601ace64"
  },
  "denied" : {
    "empty" : true
  },
  "messages" : [ ]
}

API return maps of granted and denied requests :

• Granted property maps feature urn to its related request id and allows the producer to optionnaly monitor request lifecycle listening to request event.
• Denied property maps feature urn to a list of rejection causes.