Describing and querying variables/phenomena in the API

Following both the discussion of the API and vocabularies, we still need to resolve how the API deals with vocabularies; specifically: how to make a request for a conversion type? E.g. all conversion from stage to something else? Or all conversion from stage to discharge? Or all conversions to discharge?

Some options are outlined here: http://external.opengis.org/twiki_public/HydrologyDWG/RgsAPIQuestions. The following samples use a development API and won't resolve publicly, but you get the idea..

Option 3 suggests using a service identifier for querying parameters, but also exposing a parameter/variable description that provides basic metadata for each vocab entry.

So for example, when we request a Conversion object specifically we could do this:

GET http://waterml2.csiro.au:81/rgs-api/v1/conversion/548/

"id": 548, 
    "paramFrom": {
        "id": "100.00", 
        "description": "", 
        "external_definition": "http://neiivocab.bom.gov.au/std/water/xml/wio0.2/property/wdtf-parameters/WaterCourseLevel_m"
    }, 
    "paramTo": "http://waterml2.csiro.au:81/rgs-api/v1/variable/141/", 
    "conversionperiod_set": [
        "http://waterml2.csiro.au:81/rgs-api/v1/conversion-period/434/"
    ], 
    "monitoringPoint": "http://waterml2.csiro.au:81/rgs-api/v1/monitoring-point/419015/", 
    "points": [

There are two options shown here:

1) (shown above for paramFrom) encode the parameter as an expanded object, with ID, description, and external reference to a vocab service.

2) (shown above for paramTo) encode the parameter as link to an internal service call, which resolves to:

GET /rgs-api/v1/variable/141/

{
    "id": "141", 
    "description": "", 
    "external_definition": "http://neiivocab.bom.gov.au/std/water/xml/wio0.2/property/wdtf-parameters/WaterCourseDischarge_m3s"
}

This requires one more API call, but lowers the content of the conversion encoding.

The XML response to a request like this could just be a SKOS encoding that provides seeAlso or whatever other refs/links are required.

This then allows the following calls (get all the stage-discharge conversion for specific MP):

GET http://waterml2.csiro.au:81/rgs-api/v1/conversion/?paramFrom=100.00&paramTo=141&monitoring-point=419015

Preferences

• Paul choses option 1. (the blue door)
• Feel free to drop your choice here..

-- PeterTaylor - 25 Mar 2014