CUAHIS-HIS
RSS

Navigation





Quick Search
»
Advanced Search »

PoweredBy

WaterOneFlow REST URL Discussion

RSS
Modified on 2011/02/02 08:38 by valentinedwv Categorized as Uncategorized

Issues with REST URLS

Issue:

It is simpler to develop a REST interface, that a compliant SOAP service, and there are no specifications for the URL’s or the query strings. Several organizations have developed "rest" interfaces.

Examples:

There are several examples of REST implementations:
  • USGS
  • NCDC
  • NASA
  • CUAHSI

USGS

Get Real Time Data for one day

  • http://waterservices.usgs.gov/nwis/iv?sites=01646500&period=P1D&parameterCd=00060,00065
    • {BaseURl}?sites={usgs:siteNo}&period={timePeriod}&parameterCd={usgs:variable}
  • http://waterservices.usgs.gov/nwis/iv?sites=01646500&startDT=2011-01-01&endDT=2011-01-02&parameterCd=00060,00065
    • {BaseURl}iv?sites=01646500&startDT={time:start}&endDT={time:end}&parameterCd={usgs:variable}

Daily Values

  • http://interim.waterservices.usgs.gov:80/NWISQuery/GetDV1?SiteNum=07334200&ParameterCode=00060&&StatisticCode=00003&AgencyCode=&StartDate=2000-11-16&EndDate=2000-12-15&action=Submit
    • {BaseURl}NWISQuery/GetDV1?SiteNum={usgs:siteNo}&ParameterCode={variable}&StatisticCode={usgs:statistic}&StartDate={time:start}&EndDate={time:end}&AgencyCode=&action=Submit

NCDC

  • http://www7.ncdc.noaa.gov/rest/services/values/daily/01018499999/CIG/20080101/20080131/?output=waterml&token=TOKEN
    • http://www7.ncdc.noaa.gov/rest/services/values/datasetId/stationId/variableId/{startDate}/{endDate}/

NASA

  • http://hydro1.sci.gsfc.nasa.gov/daac-bin/cuahsi/his.cgi?function=GetVaules&variable=NLDAS:NLDAS_FORA0125_H.002:apcpsfc&location=NLDAS:X0-Y0&startDate=1980-01-03T11&endDate=1980-01-04T11
    • {BaseURl}/cuahsi/his.cgi?function=GetVaules&variable={cuashi:variable}&location={cuahsi:location}&startDate={time:start}&endDate={time:end}
  • http://hydro1.sci.gsfc.nasa.gov/daac-bin/cuahsi/his.cgi?function=GetSiteInfo&location=NLDAS:X310-Y80.

Microsoft Web Service (aka WaterOneFlow)

  • http://water.sdsc.edu/lbrsdsc/cuahsi_1_1.asmx/GetValuesObject?variable=LRBSDSC:USU4&location=LRBSDSC:USU-LBR-SFLower&startDate=&endDate=&authToken=
    • {BaseURl}/cuahsi_1_1.asmx/GetValuesObject?variable={cuashi:variable}&location={cuahsi:location}&startDate={time:start?}&endDate={time:end?}&authToken={cuahsi:token}

Summary of Example

{BaseURl}?sites={usgs:siteNo}&period={timePeriod}&parameterCd={variable}
{BaseURl}NWISQuery/GetDV1?SiteNum={usgs:siteNo}&ParameterCode={variable}&StatisticCode={usgs:statistic}&StartDate={time:start}&EndDate={time:end}&AgencyCode=&action=Submit
{BaseURl}rest/services/values/datasetId/stationId/variableId/{startDate}/{endDate}/
{BaseURl}/cuahsi/his.cgi?function=GetVaules&variable={cuashi:variable}&location={cuahsi:location}&startDate={time:start}&endDate={time:end}
{BaseURl}/cuahsi_1_1.asmx/GetValuesObject?variable={cuashi:variable}&location={cuahsi:location}&startDate={time:start?}&endDate={time:end?}&authToken={cuahsi:token}

Possible Solutions

  • Ask all developers to follow the MS WebService Pattern
  • Define a Stanard Pattern.
  • Use URL Substitution, AKA OpenSearch

Solution 1: All follow the Micdorsoft WS pattern

  • Pro’s
    • Already Implemented by CUAHSI
  • Con’s
    • Not standard,
    • IF MS changes the pattern, then it breaks.

Solution 2: Define a Stanard Pattern

  • Pro’s
    • Ideal.
  • Con’s
    • Not standard,
      • IF MS changes the pattern, then it breaks.

Solution 3: URL Substitution, aka OpenSearch

  • Pro’s
    • We can map the URL's now.
    • If a groups softare changes, then they changes the
  • Con’s
    • Responsibility on Clients

OpenSearch

http://www.opensearch.org/Home

FULL USGS Example 

<?xml version="1.0" encoding="UTF-8"?>
 <OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
   <ShortName>WaterOneFlow USGS Real Time</ShortName>
   <Description>WaterOneFlow Search Service to Search the web</Description>
   <Tags>CUAHSI WaterML</Tags>
   <Contact>admin@example.com</Contact>
   <Url type="application/vnd.cuahsi.values"
        template="iv?sites=01646500&startDT={time:start}&endDT={time:end}&parameterCd={usgs:variable}"/>
   <Url type="application/vnd.cuahsi.siteInfo"
        template="http://interim.waterservices.usgs.gov/SiteFile/getSites?SiteNo={cuahsi:siteCode}&SiteType=sw,gw,sp,at,ot&SiteCode=all&Format=WaterML"/>
  <Url type="application/vnd.cuahsi.sites"
        template="http://interim.waterservices.usgs.gov/SiteFile/getSites?bbox={geo:box?}&SiteType=sw,gw,sp,at,ot&SiteCode=all&Format=WaterML"/>
   <Url type="text/html" 
        template="SOME EXAMPLE HTML PAGE"/>
   <LongName>Example.com Web Search</LongName>
    <Query role="example" searchTerms="cat" />
   <Developer>WaterOneFlow Search</Developer>
   <Attribution>
     Search data Copyright 2005, Example.com, Inc., All Rights Reserved
   </Attribution>
   <SyndicationRight>open</SyndicationRight>
   <AdultContent>false</AdultContent>
   <Language>en-us</Language>
   <OutputEncoding>UTF-8</OutputEncoding>
   <InputEncoding>UTF-8</InputEncoding>
 </OpenSearchDescription>

CUAHSI Example 

   <Url type="application/vnd.cuahsi.values"
        template="{BaseURl}/cuahsi_1_1.asmx/GetValuesObject?variable={cuashi:variable}&amp;location={cuahsi:location}&amp;startDate={time:start?}&amp;endDate={time:end?}&amp;authToken={cuahsi:token}"/>
   <Url type="application/vnd.cuahsi.siteInfo"
        template="{BaseURl}/cuahsi_1_1.asmx/GetSitesObject?site={cuahsi:location?}&amp;authToken={cuahsi:token}"/>
   <Url type="application/vnd.cuahsi.sites"
        template="{BaseURl}/cuahsi_1_1.asmx/GetSiteInfoObject?site={cuahsi:location}&amp;authToken={cuahsi:token}"/>
   <Url type="application/vnd.cuahsi.sites"
        template="{BaseURl}/cuahsi_1_1.asmx/GetVariablesObject?variable={cuashi:variable?}&amp;authToken={cuahsi:token}"/>

USGS Daily Values 

   <Url type="application/vnd.cuahsi.values"
        template="BaseURl}NWISQuery/GetDV1?SiteNum={cuahsi:siteCode}&amp;ParameterCode={cuahsi:variableCode}&amp;StatisticCode={usgs:statistic}&amp;StartDate={time:start}&amp;EndDate={time:end}&AgencyCode=&action=Submit"/>
   <Url type="application/vnd.cuahsi.siteInfo"
        template="http://interim.waterservices.usgs.gov/SiteFile/getSites?SiteNo={cuahsi:siteCode}&SiteType=sw,gw,sp,at,ot&SiteCode=all&Format=WaterML"/>
   <Url type="application/vnd.cuahsi.sites"
        template="http://interim.waterservices.usgs.gov/SiteFile/getSites?bbox={geo:box?}&SiteType=sw,gw,sp,at,ot&SiteCode=all&Format=WaterML"/>
   <Url type="text/html" 
        template="http://example.com/?q={searchTerms}&amp;pw={startPage?}"/>

NASA Example 

   <Url type="application/vnd.cuahsi.values"
        template="{BaseURl}/cuahsi/his.cgi?function=GetVaules&variable={cuashi:variable}&location={cuahsi:location}&amp;startDate={time:start}&amp;endDate={time:end}"/>
   <Url type="application/vnd.cuahsi.siteInfo"
        template="{BaseURl}/cuahsi/his.cgi?function=GetSiteslocation={cuahsi:location}"/>

NCDC Example 

   <Url type="application/vnd.cuahsi.values"
        template="rest/services/values/datasetId/stationId/variableId/{startDate}/{endDate}/"/>
   <Url type="application/vnd.cuahsi.siteInfo"
        template="{BaseURl}/cuahsi/his.cgi?function=GetSiteslocation={cuahsi:location}"/>

ScrewTurn Wiki version 3.0.1.400. Some of the icons created by FamFamFam.