Merge pull request #35 from CSIRO-enviro-informatics/describe-apis-an…

…d-components Describe apis and components
CSIRO-enviro-informatics · Feb 20, 2020 · 5da9e32 · 5da9e32
2 parents 23bb996 + 31f94bb
commit 5da9e32
Show file tree

Hide file tree

Showing 25 changed files with 108 additions and 3 deletions.
diff --git a/geometry-data-service.md b/geometry-data-service.md
@@ -0,0 +1,95 @@
+# Geometry Data Service
+
+The Geometry Data Service (GDS) is a lightweight API that has been developed in Loc-I to facilitate 
+* minting URIs for geometries to enable Linked Data functionality
+* content-negotiation for formats and representations of the geometry
+* search by point for relevant geometries across the geometry store
+* parameterise the profile of the geometry representation for a Loc-I Feature (geometry of a feature with a resolution in metres, bounding box, centroid, simplified vs. complex geom, projection/CRS)
+
+![Geometry Data Service architecture](images/geometry-data-service.png "Geometry Data Service architecture")
+
+The current Geometry Data Service uses the [pyLDAPI](https://github.com/RDFLib/pyLDAPI) to implement the Linked Data APIs.
+
+
+
+# Scope
+
+##  Mint URIs for geometries and provide an API for it
+
+* Only store (geo-referenced) geometries
+* Scoped to Earth initially
+
+Implies 
+* Ability to embed a URI Reference in a Loc-I feature instance 
+* Selecting a predicate to associate a feature with the geometry URI reference (GeoSPARQL or something else?)
+* Returning the geometry representation from somewhere (from a remote service or local geodatabase cache)
+* Content negotiation by profiles
+
+
+## Out of scope
+
+Performing extensive utility calculations on geometries (i.e. [ArcGIS GeometryService](https://www.arcgis.com/home/item.html?id=2e18b487043641538f02028cc2495c0e)).
+
+
+# Content negotiation interfaces
+
+The Geometry Data Service implements and extends conneg arrangement proposed by (Regalia et al. 2017). 
+Conneg interfaces the GDS implements are shown below:
+
+| MIME Type | Description | Returns |
+|--------------|--------------|---------|
+|text/html |Web interface |`<!DOCTYPE html><html lang="en">...`|
+|text/plain |Well-Known Text |`POLYGON((113.1016 -38.062 ...))`|
+|application/json | GeoJSON |`{"type":"Polygon","coordinates":...}`|
+|application/geo+json | GeoJSON (coming soon...)|`{"type":"Polygon","coordinates":...}`|
+|text/turtle | RDF Turtle representation using GeoSPARQL | ```_:geom1 a geo:sfPolygon , geo:Geometry ; geo:asWKT "POLYGON((113.1016 -38.062 ...))"^^geo:wktLiteral .```|
+
+GDS also implements some content profiles (refer to [W3C Conneg by Profile](https://w3c.github.io/dxwg/connegp/)):
+
+| Content profile name | Returns | Notes |
+|--------------|--------------|---------|
+|geometryview (default) | Provides the geometry as-is | Useful for using the full resolution geometry |
+|centroid | Generates the centroid for the geometry | Useful for when you only need the centroid |
+|simplifiedgeom | Applies a function to "simplify" the geometry | Useful for rendering the geometry but don't need the full resolution (smaller payload also) |
+
+The combination of the two sets of interfaces allows users to query for the geometry resource
+to suit the needs of the application.
+
+
+# Usage scenarios
+
+## Linking from a description of a feature
+
+Rather than embed a literal to the geometry in the Geosparql Feature instance,
+the GDS may be used to provide a description of the geometry via a URI reference. 
+
+Example: ASGS 2016 Meshblock Feature
+```
+<http://linked.data.gov.au/dataset/asgs2016/meshblock/20663970000> a asgs:MeshBlock,
+        geo:Feature ;
+    geo:hasGeometry <http://gds.loci.cat/dataset/asgs16_mb/20663970000> ;
+.
+```
+
+It is up to the client/user to resolve the URI ref to the Geometry via standard HTTP plus conneg (by profile and format). 
+
+## Find the respective feature(s) from the geometry
+
+Given a geometry description, we can follow links back to respective feature.
+An example of the RDF/Turtle format response for the Geometry URI 
+`http://gds.loci.cat/geometry/asgs16_mb/20663970000`: 
+```
+<http://gds.loci.cat/geometry/asgs16_mb/20663970000> a geo:Geometry,
+        sf:MultiPolygon ;
+    geox:isGeometryOf <http://linked.data.gov.au/dataset/asgs2016/meshblock/20663970000> .
+```
+
+We can then traverse back to the Feature via the value for the `geox:isGeometryOf` property.
+
+
+# References and related work
+
+* https://gnis-ld.org/ 
+* Regalia et al., Revisiting the Representation of and Need for Raw Geometries on the Linked Data Web, LDOW, 2017, http://ceur-ws.org/Vol-1809/article-04.pdf
+
+
diff --git a/images/geometry-data-service.png b/images/geometry-data-service.png
diff --git a/images/gliffy/app-developer-archetype-interactions.gliffy b/images/gliffy/app-developer-archetype-interactions.gliffy
diff --git a/images/gliffy/geometry-data-service.gliffy b/images/gliffy/geometry-data-service.gliffy
@@ -0,0 +1 @@
+{"contentType":"application/gliffy+json","version":"1.1","metadata":{"title":"untitled","revision":0,"exportBorder":false},"embeddedResources":{"index":0,"resources":[]},"stage":{"objects":[{"x":180,"y":230,"rotation":0,"id":10,"uid":"com.gliffy.shape.basic.basic_v1.default.text","width":110,"height":32,"lockAspectRatio":false,"lockShape":false,"order":4,"graphic":{"type":"Text","Text":{"tid":null,"valign":"middle","overflow":"none","vposition":"none","hposition":"none","html":"<p style=\"text-align:center;\"><span style=\"font-size: 14px; font-family: Arial; white-space: pre-wrap; font-weight: bold; line-height: 16.5px; color: rgb(0, 0, 0);\">Geo-database\n</span></p><p style=\"text-align:center;\"><span style=\"font-size: 14px; font-family: Arial; white-space: pre-wrap; font-weight: bold; line-height: 16.5px; color: rgb(0, 0, 0);\">(PostGIS)</span></p>","paddingLeft":2,"paddingRight":2,"paddingBottom":2,"paddingTop":2}},"children":null,"linkMap":[]},{"x":50.00000000000001,"y":20,"rotation":0,"id":1,"uid":"com.gliffy.shape.basic.basic_v1.default.hexagon","width":122.0000000000001,"height":90,"lockAspectRatio":false,"lockShape":false,"order":3,"graphic":{"type":"Shape","Shape":{"tid":"com.gliffy.stencil.hexagon.basic_v1","strokeWidth":2,"strokeColor":"#073763","fillColor":"#6d9eeb","gradient":false,"dropShadow":false,"state":0,"shadowX":0,"shadowY":0,"opacity":1}},"children":[],"linkMap":[]},{"x":60,"y":230,"rotation":0,"id":2,"uid":"com.gliffy.shape.basic.basic_v1.default.cylinder","width":100,"height":66.5,"lockAspectRatio":false,"lockShape":false,"order":2,"graphic":{"type":"Shape","Shape":{"tid":"com.gliffy.stencil.cylinder.basic_v1","strokeWidth":4,"strokeColor":"#073763","fillColor":"#ffffff","gradient":false,"dropShadow":false,"state":0,"shadowX":0,"shadowY":0,"opacity":1}},"children":[],"linkMap":[]},{"x":180,"y":30,"rotation":0,"id":4,"uid":"com.gliffy.shape.basic.basic_v1.default.text","width":110,"height":48,"lockAspectRatio":false,"lockShape":false,"order":1,"graphic":{"type":"Text","Text":{"tid":null,"valign":"middle","overflow":"none","vposition":"none","hposition":"none","html":"<p style=\"text-align:center;\"><span style=\"font-size: 14px; font-family: Arial; white-space: pre-wrap; font-weight: bold; line-height: 16.5px; color: rgb(0, 0, 0);\">Geometry Data Service \n</span></p><p style=\"text-align:center;\"><span style=\"font-size: 14px; font-family: Arial; white-space: pre-wrap; font-weight: bold; line-height: 16.5px; color: rgb(0, 0, 0);\">(REST)</span></p>","paddingLeft":2,"paddingRight":2,"paddingBottom":2,"paddingTop":2}},"children":null,"linkMap":[]},{"x":114,"y":64,"rotation":0,"id":9,"uid":"com.gliffy.shape.basic.basic_v1.default.line","width":100,"height":100,"lockAspectRatio":false,"lockShape":false,"order":0,"graphic":{"type":"Line","Line":{"strokeWidth":2,"strokeColor":"#000000","fillColor":"none","dashStyle":null,"startArrow":0,"endArrow":0,"startArrowRotation":"auto","endArrowRotation":"auto","ortho":false,"interpolationType":"linear","cornerRadius":null,"controlPath":[[-2.999999999999943,1],[-4,199.25]],"lockSegments":{}}},"children":null,"constraints":{"constraints":[],"startConstraint":{"type":"StartPositionConstraint","StartPositionConstraint":{"nodeId":1,"px":0.5,"py":0.5}},"endConstraint":{"type":"EndPositionConstraint","EndPositionConstraint":{"nodeId":2,"px":0.5,"py":0.5}}},"linkMap":[]}],"background":"#FFFFFF","width":290,"height":297,"maxWidth":5000,"maxHeight":5000,"nodeIndex":12,"autoFit":true,"exportBorder":false,"gridOn":true,"snapToGrid":true,"drawingGuidesOn":false,"pageBreaksOn":false,"printGridOn":false,"printPaper":"LETTER","printShrinkToFit":false,"printPortrait":true,"shapeStyles":{},"lineStyles":{"global":{}},"textStyles":{},"themeData":null}}
diff --git a/images/gliffy/loci-data-registration-process.gliffy b/images/gliffy/loci-data-registration-process.gliffy
diff --git a/images/gliffy/loci-detailed-architecture.gliffy b/images/gliffy/loci-detailed-architecture.gliffy
diff --git a/images/gliffy/loci-system-overview-ld.gliffy b/images/gliffy/loci-system-overview-ld.gliffy
diff --git a/images/gliffy/loci-system-tech-overview-feb2020-dggs-v3.gliffy b/images/gliffy/loci-system-tech-overview-feb2020-dggs-v3.gliffy
diff --git a/images/gliffy/loci-system-tech-overview-feb2020.gliffy b/images/gliffy/loci-system-tech-overview-feb2020.gliffy
diff --git a/images/gliffy/loci-system-tech-overview-jan2020.gliffy b/images/gliffy/loci-system-tech-overview-jan2020.gliffy
diff --git a/images/gliffy/loci-system-tech-overview.gliffy b/images/gliffy/loci-system-tech-overview.gliffy
diff --git a/images/gliffy/pressy.gliffy b/images/gliffy/pressy.gliffy
diff --git a/images/gliffy/pressy.png b/images/gliffy/pressy.png
diff --git a/images/graph.PNG b/images/graph.PNG
diff --git a/images/graph2.PNG b/images/graph2.PNG
diff --git a/images/loci-data-registration-process-colour.png b/images/loci-data-registration-process-colour.png
diff --git a/images/loci-data-registration-process.png b/images/loci-data-registration-process.png
diff --git a/images/loci-detailed-architecture.png b/images/loci-detailed-architecture.png
diff --git a/images/loci-system-overview-ld.png b/images/loci-system-overview-ld.png
diff --git a/images/loci-system-tech-overview-feb2020-dggs-v3.png b/images/loci-system-tech-overview-feb2020-dggs-v3.png
diff --git a/images/loci-system-tech-overview-feb2020.png b/images/loci-system-tech-overview-feb2020.png
diff --git a/images/loci-system-tech-overview-jan2020.png b/images/loci-system-tech-overview-jan2020.png
diff --git a/images/loci-system-tech-overview-nov2019.png b/images/loci-system-tech-overview-nov2019.png
diff --git a/integration-api.md b/integration-api.md
@@ -12,7 +12,7 @@ A REST API to a Loc-I Integrated Cache and other related data sources.
 
 ## Why
 
-Provides developers and technical analysts with interfaces to the [Loc-I reference cache](ref-cache.md) to build applications and query a Loc-I cache without having to know SPARQL. This allows rapid development of applications using the REST API.
+Provides developers and technical analysts with interfaces to the [Loc-I reference cache](ref-cache.md) and other sources, to build applications and query a Loc-I cache without having to know SPARQL. This allows rapid development of applications using the REST API.
 
 ## How 
 

diff --git a/technical_architecture.md b/technical_architecture.md
@@ -15,8 +15,8 @@ In particular, these provide users the ability to:
 * Query geometric topological relationships of a given location, e.g. show me all locations in a geography (or multiple geographies) that are contained within a given location. 
 
 
-![Loc-I Technical Architecture Overview](images/loci-system-tech-overview-nov2019.png "Loc-I Technical Architecture Overview")
+![Loc-I Technical Architecture Overview](images/loci-system-tech-overview-feb2020.png "Loc-I Technical Architecture Overview")
 
 ## Detailed architecture view 
 
-![Loc-I Cache Architecture](images/loci-architecture-oct19.png "Loc-I Cache Architecture")
+![Loc-I Cache Architecture](images/loci-detailed-architecture.png "Loc-I Cache Architecture")
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		{"contentType":"application/gliffy+json","version":"1.1","metadata":{"title":"untitled","revision":0,"exportBorder":false},"embeddedResources":{"index":0,"resources":[]},"stage":{"objects":[{"x":180,"y":230,"rotation":0,"id":10,"uid":"com.gliffy.shape.basic.basic_v1.default.text","width":110,"height":32,"lockAspectRatio":false,"lockShape":false,"order":4,"graphic":{"type":"Text","Text":{"tid":null,"valign":"middle","overflow":"none","vposition":"none","hposition":"none","html":"<p style=\"text-align:center;\"><span style=\"font-size: 14px; font-family: Arial; white-space: pre-wrap; font-weight: bold; line-height: 16.5px; color: rgb(0, 0, 0);\">Geo-database\n</span></p><p style=\"text-align:center;\"><span style=\"font-size: 14px; font-family: Arial; white-space: pre-wrap; font-weight: bold; line-height: 16.5px; color: rgb(0, 0, 0);\">(PostGIS)</span></p>","paddingLeft":2,"paddingRight":2,"paddingBottom":2,"paddingTop":2}},"children":null,"linkMap":[]},{"x":50.00000000000001,"y":20,"rotation":0,"id":1,"uid":"com.gliffy.shape.basic.basic_v1.default.hexagon","width":122.0000000000001,"height":90,"lockAspectRatio":false,"lockShape":false,"order":3,"graphic":{"type":"Shape","Shape":{"tid":"com.gliffy.stencil.hexagon.basic_v1","strokeWidth":2,"strokeColor":"#073763","fillColor":"#6d9eeb","gradient":false,"dropShadow":false,"state":0,"shadowX":0,"shadowY":0,"opacity":1}},"children":[],"linkMap":[]},{"x":60,"y":230,"rotation":0,"id":2,"uid":"com.gliffy.shape.basic.basic_v1.default.cylinder","width":100,"height":66.5,"lockAspectRatio":false,"lockShape":false,"order":2,"graphic":{"type":"Shape","Shape":{"tid":"com.gliffy.stencil.cylinder.basic_v1","strokeWidth":4,"strokeColor":"#073763","fillColor":"#ffffff","gradient":false,"dropShadow":false,"state":0,"shadowX":0,"shadowY":0,"opacity":1}},"children":[],"linkMap":[]},{"x":180,"y":30,"rotation":0,"id":4,"uid":"com.gliffy.shape.basic.basic_v1.default.text","width":110,"height":48,"lockAspectRatio":false,"lockShape":false,"order":1,"graphic":{"type":"Text","Text":{"tid":null,"valign":"middle","overflow":"none","vposition":"none","hposition":"none","html":"<p style=\"text-align:center;\"><span style=\"font-size: 14px; font-family: Arial; white-space: pre-wrap; font-weight: bold; line-height: 16.5px; color: rgb(0, 0, 0);\">Geometry Data Service \n</span></p><p style=\"text-align:center;\"><span style=\"font-size: 14px; font-family: Arial; white-space: pre-wrap; font-weight: bold; line-height: 16.5px; color: rgb(0, 0, 0);\">(REST)</span></p>","paddingLeft":2,"paddingRight":2,"paddingBottom":2,"paddingTop":2}},"children":null,"linkMap":[]},{"x":114,"y":64,"rotation":0,"id":9,"uid":"com.gliffy.shape.basic.basic_v1.default.line","width":100,"height":100,"lockAspectRatio":false,"lockShape":false,"order":0,"graphic":{"type":"Line","Line":{"strokeWidth":2,"strokeColor":"#000000","fillColor":"none","dashStyle":null,"startArrow":0,"endArrow":0,"startArrowRotation":"auto","endArrowRotation":"auto","ortho":false,"interpolationType":"linear","cornerRadius":null,"controlPath":[[-2.999999999999943,1],[-4,199.25]],"lockSegments":{}}},"children":null,"constraints":{"constraints":[],"startConstraint":{"type":"StartPositionConstraint","StartPositionConstraint":{"nodeId":1,"px":0.5,"py":0.5}},"endConstraint":{"type":"EndPositionConstraint","EndPositionConstraint":{"nodeId":2,"px":0.5,"py":0.5}}},"linkMap":[]}],"background":"#FFFFFF","width":290,"height":297,"maxWidth":5000,"maxHeight":5000,"nodeIndex":12,"autoFit":true,"exportBorder":false,"gridOn":true,"snapToGrid":true,"drawingGuidesOn":false,"pageBreaksOn":false,"printGridOn":false,"printPaper":"LETTER","printShrinkToFit":false,"printPortrait":true,"shapeStyles":{},"lineStyles":{"global":{}},"textStyles":{},"themeData":null}}
-Original file line number
+Diff line change
@@ Expand Up @@
     ## Why
-    Provides developers and technical analysts with interfaces to the [Loc-I reference cache](ref-cache.md) to build applications and query a Loc-I cache without having to know SPARQL. This allows rapid development of applications using the REST API.
+    Provides developers and technical analysts with interfaces to the [Loc-I reference cache](ref-cache.md) and other sources, to build applications and query a Loc-I cache without having to know SPARQL. This allows rapid development of applications using the REST API.
     ## How
@@ Expand Down @@