Home

This page documents discussion and design of a Loc-I Integration API

Name

Loc-I Integration API

...

1. Goal/scope

Complement existing Loc-I (see v2 component architecture) with the addition of a Loc-I Integration API (preferably OpenAPIv3) for these purposes.

Primary purposes

Provide a uniform interface/standardise access to Loc-I cache resources for common operations (without needing to know SPARQL)
Separate front-end/client-application-specific logic from query logic of common operations (Integration API interfacing with Application-specific APIs)
Maintain a separation between API and backend implementations (changes in data models, triplestore/database implementations, load balancing, etc)
Enable rapid development of new applications from reuse of query logic of common operations

Secondary purposes

Provide a platform to facilitate open-source development of additional APIs
Cache common operations for performance
Allow API deployment in separate cache configs
... (probably others)

Future design goals

Federated queries, queries across multiple caches

\

User stories

User story 1 lookup location

As a/an... Enterprise data warehouse manager

I want to... a) Find spatial identifier(s) for a location (geospatial feature) in my database denoted by a (i) name (ii) text description (iii) lat/long, DGGS, or GPS location

             b) Add location information for a new entry for an observation or data point based on some location description (text)

so that... I can ensure consistency across my data warehouse and provide opportunities to integrate with other data

\

User story 2 correlate with other indexed locations

As a/an... Spatial data analyst

I want to... a) For a location (geospatial feature) in dataset A find which location(s) (geospatial feature(s)) from dataset B are contained within it

             b\) map observations/data from one geography (Geofabric) to reporting
             units in another geography (ASGS) (reapportionment)
             
             c\) For a location (geospatial feature), find related locations
             (geospatial feature) within the dataset by some relationship (within,
             contains, overlap)

so that... I can understand influences from other domains on the location (geospatial feature) I'm interested in and retrieve related locations

\

Issues/concerns

1. What is deemed as common operations in the Integration API bucket?

2. Communicating that the Integration API is a complement to the SPARQL API - full power of Loc-I and the Linked Data features

\

API design and implementation

\

What do we design and implement as the Integration API?

Core Integration API endpoints

+------------+------------+ | Endpoints | User story | Priority | | | | | | | | | | | +============+============+ | ~~https:// | 2 | api.loci.c | | | at/v1/obje | | | ct/contain | | | s~~ | | | | | https | | ://api.loc | | | i.cat</spa | | n>/v1/obje | | ct/overlap | | | s | | | | | https | | ://api.loc | | | i.cat/v1/l | | | ocation/ov | | | erlaps</sp | | an> | | | | | | | | | | | | | | | | +------------+------------+ | ~~https | | ://api.loc | | | i.cat</spa | | n>/v1/obje | | cts/within | | | ~~ | | | | | | https | | ://api.loc | | | i.cat</spa | | n>/ | | | v1/locatio | | | n/within | | +------------+------------+ | ~~https | | ://api.loc | | | i.cat</spa | | n>/v1/obje | | ct~ | | | ~ | | | | | | https | | ://api.loc | | | i.cat</spa | | n>/v1/reso | | urce | +------------+------------+ | https | | ://api.loc | | | i.cat</spa | | n>/v1/loca | | tions</spa | | n> | | | | | | | +------------+------------+ | https | | ://api.loc | | | i.cat</spa | | n>/v1/link | | sets | +------------+------------+ | https | | ://api.loc | | | i.cat</spa | | n>/v1/data | | sets | +------------+------------+ | https | | ://api.loc | | | i.cat</spa | | n>/v1/obje | | ct/find-by | | | -name</spa | | n> | | | | | https | | ://api.loc | | | i.cat</spa | | n>/v1/loca | | tion/find- | | | by-name</s | | pan> | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | +------------+------------+ | https | | ://api.loc | | | i.cat</spa | | n>/v1/obje | | ct/find-by | | | -point</sp | | an> | | | | | https | | ://api.loc | | | i.cat</spa | | n>/v1/loca | | tion/find- | | | by-point</ | | span> | +------------+------------+ | https | | ://api.loc | | | i.cat</spa | | n>/v1/loca | | tion/find- | | | by-polygon | | | | | +------------+------------+ ------------+------------+------------+------------+------------+ | HTTP | Parameters | Expected | Notes | | | | response | | | (1 = | | | | | | highest | | | | | | priority, | | | | | | 3=lowest) | | | | | ============+============+============+============+============+ | 1 | GET | uri={lociU | List of | Prefer | | | ri} | URIs | 'location' | | | | denoting | rather | | | Areas='Tru | things | than | | | | e' | that | 'object' | | | | contains | as it is | rel="nofollow">https://ap | | | | includePer | lociUri | consistent | | | centage='T | locationTh | with the | | | rue' | ing | definition | | | | | e.g. | | | ~~FullCont | | prov:Locat | | | ainment='F | | ion | | | alse'~~ | | | | | | | Prefer | | | page={page | | exclusive | | | num} | | contains. | | | | | | | | offset={of | | | | | fsetnum} | | | | | | | | | | limit={num | | | | | results} | | | ------------+------------+------------+------------+------------+ | 1 | GET | uri={lociU | List of | For | | | ri} | URIs | partial | | | | | denoting | and full | | | Areas='Tru | things | contains/w | | | | e' | that | ithins | | | | | overlaps | | | | includePer | lociUri | | | | | centage='T | locationTh | | | | rue' | ing | | | | | | | | | | FullContai | | | | | | nment='Fal | | | | | se' | | | | | | | | | | page={page | | | | | | num} | | | | | | | | | | | offset={of | | | | | fsetnum} | | | | | | | | | | limit={num | | | | | results} | | | ------------+------------+------------+------------+------------+ | 1 | GET | uri={lociU | List of | Prefer | | | ri} | URIs | exclusive | | | | | denoting | within. | | | Areas='Tru | things | | | | | e' | that are | | | | | | within | | | | includePer | lociUri | | | | centage='T | locationTh | | | | rue' | ing | | | | | | | | | | page={page | | | | | | num} | | | | | | | | | | | offset={of | | | | | fsetnum} | | | | | | | | | | | limit={num | | | | | results} | | | | | | | | ------------+------------+------------+------------+------------+ | 1 | GET | uri={ | of the | the triple | | | lociUri}</ | ~~object~~ | store | | | | span> | resource | | | | | denoted by | | | | | | the | | | | | | lociUri. | | | | | This could | | | | | be an | | | | | instance | | | | | | of | | | | | (geo:Featu | | | | | | re | | | | | or | | | | | | prov:Locat | | | | | ion) | | | | | | or | | | | | | loci:Links | | | | | | et | | | | | | | | ------------+------------+------------+------------+------------+ | ? | GET | page={page | List of | Might be | | | num} | URIs | an easy | | | | | denoting | endpoint | | | offset={of | things | to | | | | fsetnum} | that | implement | | | | are of | | | | | limit={num | type | | | | | results} | geo:Featur | | | | | | e | | | | | | or | | | | | prov:Locat | | | | | ion | | ------------+------------+------------+------------+------------+ | ? | GET | page={page | List of | Might be | | | num} | URIs | an easy | | | | | denoting | endpoint | | | offset={of | things | to | | | | fsetnum} | that are | implement | | | | of type | | | | | limit={num | loci:Links | | | | | results} | et | | | | | | | | | | | | | | ------------+------------+------------+------------+------------+ | ? | GET | page={page | List of | Might be | | | num} | URIs | an easy | | | | | denoting | endpoint | | | offset={of | things | to | | | | fsetnum} | that are | implement | | | | of type | | | | | limit={num | loci:Datas | | | | | results} | et | | | | | | | | | | | | | | ------------+------------+------------+------------+------------+ | 2 | GET | name={quer | Query by | Option | | | y | text | 1. Could | | | | text} | (multiple | implement | | | | fields) | this as a | | | | dataset={d | for a | sparql | | | ataset | location | regex | | | | name, e.g. | (geospatia | query if | | | | asgs2016} | l | harmonised | | | | feature) | to | | | | | | prefLabels | | | | | | for all | | | | | names. | | | | | | Requires | | | | | work to | | | | | | harmonise | | | | | how labels | | | | | | are | | | | | represente | | | | | | d. | | | | | | | | | | | Option | | | | | | 2. | | | | | | Implement | | | | | this as a | | | | | sparql | | | | | regex | | | | | query on | | | | | the | | | | | multiple | | | | | text label | | | | | fields. | | | | | Hackish | | | | | option to | | | | | option-1. | | | | | | | | | | Option | | | | | 3. Else, | | | | | might need | | | | | to think | | | | | about | | | | | indexing | | | | | this | | | | | elsewhere | | | | | e.g. | | | | | elasticsea | | | | | rch. | ------------+------------+------------+------------+------------+ | 3 | GET | lat={lat} | Query by | Handy but | | | | point for | might | | | | long={long | a location | require a | | | } | (geospatia | spatial db | | | | | l | engine to | | | filter={da | feature) | return | | | | taset | | answers | | | | name eg. | | | | | asgs2016} | | | | | | (optional) | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | ------------+------------+------------+------------+------------+ | 4 | GET | polygon={p | Query by | Handy but | | | } | polygon | might | | | | | for a | require a | | | | location | spatial db | | | | | (geospatia | engine to | | | | l | return | | | | | feature) | answers | | | | | | | | | | | | | | | | | | | | | | ------------+------------+------------+------------+------------+

\

Unclear if in Loc-I Integration API {#unclear-if-in-loc-i-integration-api .auto-cursor-target}

+--------------------+--------------------+--------------------+--------------------+ | Endpoints | HTTP | Parameters | Expected response | +====================+====================+====================+====================+ | <sp | | | answer of the | | an | | to={lociUri} | reapportionment | | class="nolink">htt | | | function | | ps://api.loci.cat< | | value={some value} | | | /span>/v1/o | | | | | bject/reapportion | | | | +--------------------+--------------------+--------------------+--------------------+ | <sp | | | | | an | | | | | class="nolink">htt | | | | | ps://api.loci.cat< | | | | | /span>/v1/sparql</ | | | | | span> | | | | +--------------------+--------------------+--------------------+--------------------+

How do we implement the Integration API?

Since GA and CSIRO teams are familiar with Python, first cut choose a Python implementation. Something that can help automate generation of a swagger doc/api for things implemented in the Integration API.

\

Action items

2 incomplete Leighton, Ben (L&W, Clayton) to coordinate the team (Sommer, Ashley (L&W, Dutton Park) Cox, Simon (L&W, Clayton) Seaton, Shane (L&W, Black Mountain) ) to work on v1 development and testing of loci integration API and refactoring of appropriate bits of excelerator/iderdown.

\

References

\

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Home

1. Goal/scope

Primary purposes

Secondary purposes

Future design goals

so that... I can ensure consistency across my data warehouse and provide opportunities to integrate with other data

so that... I can understand influences from other domains on the location (geospatial feature) I'm interested in and retrieve related locations

What do we design and implement as the Integration API?

Core Integration API endpoints

Unclear if in Loc-I Integration API {#unclear-if-in-loc-i-integration-api .auto-cursor-target}

How do we implement the Integration API?

Action items

References

Uh oh!

Uh oh!

Clone this wiki locally