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 (asPATCH
HTTP requests) or deletion requests (asDELETE
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 valueFeature
, - 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 expectedproperties
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 calledStorage 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 |
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 |
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 |
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 valueFeatureCollection
, - 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"
}
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.