Skip to main content
Version: 1.13.0

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).

Feature management architectural concepts

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 :

{
"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

PathTypeDescriptionOptional
idStringId from provider
urnStringUnique feature identifer based on provider identifier with TEST:REQUEST:2342
danger

Urn is only expected in update and deletion requests!

Files

PathTypeDescriptionOptional
locations[].storageStringStoragetrue
locations[].urlStringUrl location
attributes.dataTypeStringRAWDATA, QUICKLOOK_SD, QUICKLOOK_MD, QUICKLOOK_HD, DOCUMENT, THUMBNAIL, DESCRIPTION
attributes.mimeTypeStringMIME type
attributes.filenameStringFilename
attributes.filesizeNumberFile sizetrue
attributes.algorithmStringChecksum algorithmtrue
attributes.checksumStringChecksumtrue
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

PathTypeDescriptionOptional
metadata.overrideBooleanIndicate wether the previous version should be deletedtrue
metadata.sessionStringArbitrary session name to classify data for human operators
metadata.sessionOwnerStringArbitrary session owner to classify data for human operators
metadata.storagesArrayTarget storages if there are files to store (may be empty!)true
metadata.storages[].pluginBusinessIdStringStorage plugin identifier (previously configured in Storage Management
metadata.storages[].targetTypesArrayList of data object types accepted by this storage locationtrue
metadata.storages[].storePathStringDirectory in which to store the filetrue
metadata.priorityStringHIGH, 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.