enable filtering of featureType in /location/contains

[jyucsiro]

The current behaviour of /location/contains is that it returns all features that is contained within it.

It would be good to have an input flag, i.e. output_featuretype_uri, to enable users to specify which FeatureType instances are returned.

Example:

• Input: MeshBlock X, output_featuretype_uri=http://linked.data.gov.au/def/gnaf#Address
• Output: [ list of G-NAF addresses contained in a meshblock ]

This would be useful for IDerdown for crosswalking.

[dr-shorthair]

Where is the API documented? Is this a HTTP GET or POST?

[jyucsiro]

At the moment, it's deployed at https://api2.loci.cat/ and it's documented in the swagger/openapi doc at https://api2.loci.cat/api/v1/doc

This is a HTTP GET currently.

[dr-shorthair]

OK - so an example query might be

https://api2.loci.cat/api/v1/location/contains?uri=http://linked.data.gov.au/dataset/asgs2016/statisticalarealevel3/80106

I wonder if it should also be implemented via

http://linked.data.gov.au/dataset/asgs2016/statisticalarealevel3/80106/contains

(probably as a redirect to the first version of course)

[dr-shorthair]

BTW - could example calls be added to the Swagger?

[jyucsiro]

OK - so an example query might be

https://api2.loci.cat/api/v1/location/contains?uri=http://linked.data.gov.au/dataset/asgs2016/statisticalarealevel3/80106

yes

I wonder if it should also be implemented via
http://linked.data.gov.au/dataset/asgs2016/statisticalarealevel3/80106/contains
(probably as a redirect to the first version of course)

the integration-api (api2.loci.cat) and the LD APIs (where http://linked.data.gov.au/dataset/asgs2016/statisticalarealevel3/80106 resolves to) are two different components.

what you are suggesting sounds like a feature for the LD API to extend it with spatial REST operators?

[dr-shorthair]

Yes, I realise it requires ops on a different server, which may not be available.
But to my eyes the API is a traditional RPC, merely dressed up as a URI.
The actual 'resource' is a 'contains-service' that takes arguments.

I'm suggesting a more RESTful pattern might be possible: where http://yadayada/contains identifies a resource composed of the set of features contained in the base resource.

However, if a contains-service with arguments is what the market expects, then that is probably what we should provide.

[jyucsiro]

agree, but lets separate concerns on the components.

for the integration-api (which interfaces with a cache of those LD resources) - agree
https://api2.loci.cat/api/v1/location/contains?uri=http://linked.data.gov.au/dataset/asgs2016/statisticalarealevel3/80106
... is more rpc style

the team did discuss an alternative when we were designing the APIs (more RESTful api endpoint for the call), which would be
https://api2.loci.cat/api/v1/location/{uri}/contains

e.g. for uri http://linked.data.gov.au/dataset/asgs2016/statisticalarealevel3/80106
the call would be:
https://api2.loci.cat/api/v1/location/http%3A%2F%2Flinked.data.gov.au%2Fdataset%2Fasgs2016%2Fstatisticalarealevel3%2F80106/contains

where the URI is url-encoded. it is an option that the team has discussed previously. the reluctance was on the url-encoding of the URI which is an extra step...

note: some doco here - https://github.com/CSIRO-enviro-informatics/loci-integration-api/wiki

[dr-shorthair]

url-encoded is ugly if you do it manually.
https://www.url-encode-decode.com/

[jyucsiro]

even if done automatically, it's an extra step a developer has to make (maybe not a big step). there are benefits to having it more RESTful and worth exploring.