Configuring and Using Web Services

Introduction

Hydstra provides tools to enable access to Hydstra data via SOAP and REST web services.
The REST web service uses the GET method by default (via a standard URL request). The web service also supports POST requests.

To configure Hydstra web services you will need the following:

•      A Hydstra/WSI (or WEB) licence in your HYACCESS.INI file

•      A user in PASSWD with a WSI or WEB licence (any level)

•      The service must run using a Hydstra user with a WSI or WEB licence

Through the implementation of custom code (to initiate a data request and process the data response) you have direct access to the data you may require for data modelling, data reports or new web based data presentation.

Custom code for SOAP may be developed on any software platform that supports SOAP.

A template Perl script is provided as a web service gateway to data access methods provided via the Hydstra DLL (HYDLLP) in the host Hydstra system.

The template Hydstra Perl web service is supplied in the  ..\web\wsys\cgi  folder and its URL will be something like http://127.0.0.1/cgi/webservice.pl

The related WSDL (Web services Description Language) file URL will be http://127.0.0.1/wini/webservice.wsdl

Configuring the web server environment

It is assumed that you have synchronised your Hydstra system to your web server using Syncovery or a similar tool.

Further, you have already added all the required web userclass records to CODES:PWWEBUC via the SYSADMIN Manage and added and configured the required users to PASSWD.

In addition you have already added the global environment variables PERL5LIB (equal to your Hydstra RUNPATH) and added RUNPATH and the Perl BIN path to the PATH environment variable.

You have also installed IIS, created a web site whose root is WEBPATH ( ..\hyd\web), added a script mapping for Perl and given the IUSR account Full Control permissions to the whole Hydstra folder structure.

You must now create a virtual directory 'wsi' for the WINIPATH WSI folder (..\hyd\web\wini\wsi\).

Configurable web services

By default the web service will retrieve data from the host Hydstra system according to its HYCONFIG environment. If you wish to establish a web service called from your domain that accesses data in an alternative Hydstra dataset, you may clone the template web service Perl script and direct it to use a different HYCONFIG environment as follows.

Copy  ..\hyd\web\wsys\cgi\webservice.pl  to a labelled sub folder of the WINIPATH WSI folder (e.g. ..\hyd\web\wini\wsi\dwr\webservice.pl).
Create the folders if they do not already exist.

Open the file with a flat text editor (we recommend Notepad++) and set the variable $CONFPATH to the full path and filename of a HYCONFIG ini file that establishes your desired web service environment. Do NOT edit any other code in the Perl script.
For example:

my $CONFPATH = 'C:/Hydstra/webv10/hyd/hyconfigws.ini';

NOTE: the HYCONFIG ini file may have any name (not just HYCONFIG.INI) and can be located in any accessible folder so long as the matching HYACCESS file is present in the same folder. (Forward slashes in the CONFPATH setting are acceptable.)
The HYCONFIG file must contain appropriate [Path Prefixes] settings.
It is recommended that you should make the \TEMP\ setting the same as that of your host Hydstra system so that your scheduled WEBCLEAN task will be able to remove stale temporary folders and files.

Here are some example HYCONFIG files for different scenarios:
1. a different system (and its standard DAT path):

[Version]
Version = 1

[Path Prefixes]
\HYD\=C:\hydstra\v10
\TEMP\=C:\hydstra\prod

2. the host system and a non-standard DAT path:

[Version]
Version = 1

[Path Prefixes]
\HYD\=C:\hydstra\prod
\HYD\DAT\=C:\hydstra\project
\TEMP\=C:\hydstra\prod

3. a different system and a non-standard DAT path:

[Version]
Version = 1

[Path Prefixes]
\HYD\=C:\hydstra\v10
\HYD\DAT\=C:\hydstra\v10\proj
\TEMP\=C:\hydstra\prod

You will also need to clone and amend the WSDL file from  ..\hyd\web\wini\  to match your requirements.

The REST URL for your configured web service will be something like

http://127.0.0.1/wsi/dwr/webservice.pl?{"function":"get_variable_list","version":1,"params":{"site_list":"gw000002","datasource":"CP"}}

Please contact KISTERS if you require assistance with web services scripting.

Web service queueing

To manage server load due to excessive web service calls, jobs are automatically queued using Perl. Three environment variables may be set to override defaults for maximum concurrent jobs, maximum age of jobs and the port used for job queue management communications. Each environment variable may be set in the configurable script (e.g. in the WSI folder) in Perl using the $ENV{setting} syntax, or in Control Panel -> System -> Advanced -> Environment Variables…
IMPORTANT: You must reboot the webserver after setting these system level environment variables.

MAXWSTHREADS – the maximum number of concurrent web service threads.
This limits the number of concurrent DLL calls by the web service processes – default 2

WSJOBMAXAGE – the maximum age of web service jobs (in seconds).
This limits the length of time a web service DLL call job will wait in the queue before quitting – default 300

WSSOCKETPORT – the port used for socket inter process communication to manage web service queueing – default 7890

WSMAXQLENGTH – maximum number of DLL jobs that may be added to the queue – default 20

 

REST Request and Response with JSON

The data request is made by passing a JSON structure appended as a URL query. For example:

http://realtimedata.water.nsw.gov.au/cgi/webservice.pl?{"params":{"site_list":"201001","start_time":"19750801000000","varfrom":"100.00","interval":"day","varto":"100.00","datasource":"A","end_time":"19750802000000","data_type":"mean","multiplier":"1"},"function":"get_ts_traces","version":"2"}

The details of the request JSON structure will depend upon which DLL JSONCall function you choose. The example uses the get_ts_traces DLL function. Please see the HYDLLP documentation for the latest available function names and parameters.

The response to the previous request may look something like this:

{"buff_required": 613, "buff_supplied": 50000, "error_num": 0, "_return": {"traces": [{"trace": [{"q": 130, "v": "0.367", "t": 19750801000000}, {"q": 130, "v": "0.365", "t": 19750802000000}], "site": "201001", "varfrom_details": {"subdesc": "", "variable": "100.00", "short_name": "Level (Metres)", "name": "Stream Water Level", "units": "Metres"}, "site_details": {"short_name": "OXLEY @ EUNGELLA", "name": "OXLEY RIVER AT EUNGELLA"}, "compressed": "0", "quality_codes": {"zzzzzz_130": "Not quality coded - subject to change"}, "varto_details": {"subdesc": "", "variable": "100.00", "short_name": "Level (Metres)", "name": "Stream Water Level", "units": "Metres"}}]}}

 

The REST web service may also be used for Hydstra systems with multiple DAT paths. The web portal must be correctly configured with a set of web userclasses with matching login credentials in the PASSWD table (the users' PASSWD:WEBUSERCLS fields must be populated). In addition there must exist a HYCONFIG template file for the userclass residing in WGENPATH (..\hyd\web\wgen) called hyconfig.[userclass].ini. For example:
..\hyd\web\wgen\hyconfig.admin.ini
The template file may be generated by the main portal WEBBUILDER process or you must create it yourself.

To enable the web service to access the correct data you must supply the username and password of the required userclass user as part of the web service URL.

http://mydomain.com/cgi/webservice.pl?{"function":"get_db_info","version":"3","params":{"table_name":"site","return_type":"array"}}&user=myname&pass=mypassword

The REST web service may also optionally generate a naked JSON data structure by passing the parameter naked=1. The response would look like:

{"traces": [{"trace": [{"q": 130, "v": "0.367", "t": 19750801000000}, {"q": 130, "v": "0.365", "t": 19750802000000}], "site": "201001", "varfrom_details": {"subdesc": "", "variable": "100.00", "short_name": "Level (Metres)", "name": "Stream Water Level", "units": "Metres"}, "site_details": {"short_name": "OXLEY @ EUNGELLA", "name": "OXLEY RIVER AT EUNGELLA"}, "compressed": "0", "quality_codes": {"zzzzzz_130": "Not quality coded - subject to change"}, "varto_details": {"subdesc": "", "variable": "100.00", "short_name": "Level (Metres)", "name": "Stream Water Level", "units": "Metres"}}]}

 

The REST web service response structures contain special key modifications (pre-appending ‘_’ to the return key and pre-appending zzzzzz_ to all keys starting with a digit. (These modifications were added to support fussy behaviour in browser Javascript code which is now not essential due to better browser standards compliance and new JSON parsing techniques.)
This behaviour is the default but you may omit these modifications if you specify the parameter ver=2. For example:

http://127.0.0.1/cgi/webservice.pl?{"function":"get_latest_ts_values","version":"2","params":{"site_list":"201001","datasource":"A","trace_list":[{"varfrom":"100.00","varto":"100.00"}]}}&ver=2

will return:

{"buff_required": 220, "buff_supplied": 50000, "error_num": 0, "return": {"201001": [{"varfrom": "100.00", "values": [{"time_start": "", "p": "", "time_end": "", "time": "20150728133000", "q": 3, "v": "0.434", "trend": "-"}], "varto": "100.00"}]}}

instead of:

{"buff_required": 220, "buff_supplied": 50000, "error_num": 0, "_return": {"zzzzzz_201001": [{"varfrom": "100.00", "values": [{"time_start": "", "p": "", "time_end": "", "time": "20150728133000", "q": 3, "v": "0.434", "trend": "-"}], "varto": "100.00"}]}}

 

Normally the web service supplies the content type header text/html for use in web browsers. To specify an alternative, you must append the mime parameter. The options are html and csv. For example:

http://127.0.0.1/cgi/webservice.pl?{"function":"get_latest_ts_values","version":"2","params":{"site_list":"201001","datasource":"A","trace_list":[{"varfrom":"100.00","varto":"100.00"}]}}&ver=2&mime=csv

which will return the MIME header text/csv.

 

REST requests with conventional parameter pairs

As an alternative to the JSON request format, you may use conventional parameter pairs on some calls.
This approach is currently only available for get_ts_traces, get_latest_ts_values, get_db_info but may be extended to support other calls in the future.
For example:

http://127.0.0.1/cgi/webservice.pl?function=get_ts_traces&site_list=HYDSYS01,HYDSYS02&datasource=A&varfrom=100.00&varto=100.00&start_time=19750801000000&end_time=19750802000000&data_type=mean&interval=day&multiplier=1

 

http://127.0.0.1/cgi/webservice.pl?function=get_latest_ts_values&site_list=hydsys01&datasource=A&varfrom=100.00&varto=100&lookback=60

 

http://127.0.0.1/cgi/webservice.pl?function=get_db_info&field_list=bdate,bench,elev,rlgd,method&table_name=bench&sitelist_filter=201001

 

REST response in CSV format

As an alternative to the JSON response format, you may request CSV format (for JSON and parameter pair requests) using the parameter format=csv.
This approach is currently only available for get_ts_traces, get_latest_ts_values, get_db_info but may be extended to support other calls in the future.
For example:

http://127.0.0.1/cgi/webservice.pl?{"function":"get_db_info","version":3,"params":{"table_name":"site","field_list":["station","stname"],"return_limit":10,"return_type":"array"}}&format=csv

returns:

station,stname

0,Dummy Site for Hydstra Purposes

012001,HOMESTEAD CREEK AT FOWLERS GAP

012002,FRIESLICH CREEK AT FRIESLICH DAM

012003,FOWLERS CREEK AT FOWLERS GAP

040000,ABBOTSFORD (CBM)

040001,ACACIA VALE (CBM)

040002,AMAMOOR (CBM)

040003,AMAMOUR EAST (CBM)

040004,AMBERLEY AMO (CBM)

040005,ANDERLEIGH (CBM)

 

http://127.0.0.1/cgi/webservice.pl?function=get_latest_ts_values&site_list=hydsys01&datasource=A&varfrom=100.00&varto=100&lookback=60&format=csv

returns:

site,var,time,value,quality,trend
HYDSYS01,100.00,19870226101500,0.049,1,0

 

If you use the alternative parameter format=csvc, a trailing comma will be appended to the end of every line. For example:

site,var,time,value,quality,trend,
HYDSYS01,100.00,19870226101500,0.049,1,0,

 

Sample VBA Excel REST code

Sample provided at ..\HYD\SYS\perl\examples\webservice.bas

Option Explicit

Sub http()
    Dim url As String
    Dim MyRequest As Object
    Set MyRequest = CreateObject("WinHttp.WinHttpRequest.5.1")
   
    ' MyRequest.Open "GET", "http://203.12.195.133/cgi/webservice.pl?wsver"
    url = "http://203.12.195.133/cgi/webservice.pl?{""function"":""get_db_info"",""version"":""3"",""params"":{""table_name"":""site"",""return_type"":""hash"",""filter_values"":{""station"":""221001""}}}&ver=2"
    'url = "http://data.water.vic.gov.au/cgi/webservice.pl?{""function"":""get_db_info"",""version"":""3"",""params"":{""table_name"":""site"",""return_type"":""hash"",""filter_values"":{""station"":""221001""}}}&ver=2"
   
    ' MsgBox url
   
    MyRequest.Open "GET", url
    MyRequest.send
   
    MsgBox MyRequest.responseText

End Sub

 

POST requests

To avoid the URL length limit, you may make web service requests with the POST method.

 

SOAP Request and Response

The data request is a block of XML which includes a JSON data structure specifying:

•      a Hydstra DLL function name

•      the function's parameter names and values

•      the version number of the DLL data request protocol

plus the buffer size for the data response (in bytes).

Please see the HYDLLP documentation for the latest available function names and parameters.

 

For example, use the following to request the mean daily stream level archive data for sites HYDSYS01 and HYDSYS02  from 1/8/1975 to 1/9/1975:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <JSonCall xmlns="http://203.3.195.115/WebService">
      <c-gensym5 xsi:type="xsd:string">
        {"params":
          {"site_list": "HYDSYS01,HYDSYS02",
          "start_time": "19750801000000",
          "varfrom": "100.00",
          "interval": "day",
          "varto": "100.00",
          "datasource": "A",
          "end_time": "19750901000000",
          "data_type": "mean",
          "multiplier": "1"},
        "function": "get_ts_traces",
        "version": 1}
        }
      </c-gensym5>
      <c-gensym7 xsi:type="xsd:int">
        1000000
      </c-gensym7>
    </JSonCall>
  </soap:Body>
</soap:Envelope>

The data response is a block of XML containing a JSON data structure including:

•      a process error code (and message if necessary)

•      the size of the response (bytes)

•      various relevant meta data plus the requested data types and values

•      the size of the supplied buffer size (bytes)

The corresponding response XML is:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <JSonCallResponse xmlns="http://203.3.195.115/WebService">
      <s-gensym3 xsi:type="xsd:string">
        {"error_num":0,
        "buff_required":"3477",
        "return":{
          "traces":[{
            "site_details":{
              "short_name":"Hydstra Test Station",
              "name":"Hydstra Test Station - Composite data"},
            "quality_codes":{
              "1":"Good continuous records"},
            "trace":[
              {"v":"0.363","t":19750801000000,"q":1},
              {"v":"0.368","t":19750802000000,"q":1},
              {"v":"0.363","t":19750803000000,"q":1},
              {"v":"0.464","t":19750804000000,"q":1},
              {"v":"0.505","t":19750805000000,"q":1},
              {"v":"0.417","t":19750806000000,"q":1},
              {"v":"0.368","t":19750807000000,"q":1},
              {"v":"0.318","t":19750808000000,"q":1},
              {"v":"0.294","t":19750809000000,"q":1},
              {"v":"0.285","t":19750810000000,"q":1},
              {"v":"0.308","t":19750811000000,"q":1},
              {"v":"0.461","t":19750812000000,"q":1},
              {"v":"0.507","t":19750813000000,"q":1},
              {"v":"0.457","t":19750814000000,"q":1},
              {"v":"0.396","t":19750815000000,"q":1},
              {"v":"0.369","t":19750816000000,"q":1},
              {"v":"0.354","t":19750817000000,"q":1},
              {"v":"0.344","t":19750818000000,"q":1},
              {"v":"0.328","t":19750819000000,"q":1},
              {"v":"0.275","t":19750820000000,"q":1},
              {"v":"0.251","t":19750821000000,"q":1},
              {"v":"0.243","t":19750822000000,"q":1},
              {"v":"0.237","t":19750823000000,"q":1},
              {"v":"0.228","t":19750824000000,"q":1},
              {"v":"0.222","t":19750825000000,"q":1},
              {"v":"0.221","t":19750826000000,"q":1},
              {"v":"0.267","t":19750827000000,"q":1},
              {"v":"0.349","t":19750828000000,"q":1},
              {"v":"0.300","t":19750829000000,"q":1},
              {"v":"0.254","t":19750830000000,"q":1},
              {"v":"0.231","t":19750831000000,"q":1},
              {"v":"0.220","t":19750901000000,"q":1}],
            "varfrom_details":{
              "short_name":"Level     (Metres)",
              "subdesc":"",
              "variable":" 100.00",
              "units":"Metres","name":"Stream Water Level"},
            "site":"HYDSYS01",
            "varto_details":{
              "short_name":"Level     (Metres)",
              "subdesc":"",
              "variable":" 100.00",
              "units":"Metres",
              "name":"Stream Water Level"}
            },
            {"site_details":{
               "short_name":"Hydstra Test Station",
               "name":"Hydstra Test Station - Secondary rainfall data"        },
             "quality_codes":{
               "1":"Good continuous records"},
             "trace":[
               {"v":"0.363","t":19750801000000,"q":1},
               {"v":"0.368","t":19750802000000,"q":1},
               {"v":"0.363","t":19750803000000,"q":1},
               {"v":"0.464","t":19750804000000,"q":1},
               {"v":"0.505","t":19750805000000,"q":1},
               {"v":"0.417","t":19750806000000,"q":1},
               {"v":"0.368","t":19750807000000,"q":1},
               {"v":"0.318","t":19750808000000,"q":1},
               {"v":"0.294","t":19750809000000,"q":1},
               {"v":"0.285","t":19750810000000,"q":1},
               {"v":"0.308","t":19750811000000,"q":1},
               {"v":"0.461","t":19750812000000,"q":1},
               {"v":"0.507","t":19750813000000,"q":1},
               {"v":"0.457","t":19750814000000,"q":1},
               {"v":"0.396","t":19750815000000,"q":1},
               {"v":"0.369","t":19750816000000,"q":1},
               {"v":"0.354","t":19750817000000,"q":1},
               {"v":"0.344","t":19750818000000,"q":1},
               {"v":"0.328","t":19750819000000,"q":1},
               {"v":"0.275","t":19750820000000,"q":1},
               {"v":"0.251","t":19750821000000,"q":1},
               {"v":"0.243","t":19750822000000,"q":1},
               {"v":"0.237","t":19750823000000,"q":1},
               {"v":"0.228","t":19750824000000,"q":1},
               {"v":"0.222","t":19750825000000,"q":1},
               {"v":"0.221","t":19750826000000,"q":1},
               {"v":"0.267","t":19750827000000,"q":1},
               {"v":"0.349","t":19750828000000,"q":1},
               {"v":"0.300","t":19750829000000,"q":1},
               {"v":"0.254","t":19750830000000,"q":1},
               {"v":"0.231","t":19750831000000,"q":1},
               {"v":"0.220","t":19750901000000,"q":1}],
             "varfrom_details":{
               "short_name":"Level     (Metres)",
               "subdesc":"",
               "variable":" 100.00",
               "units":"Metres",
               "name":"Stream Water Level"},
             "site":"HYDSYS02",
             "varto_details":{
               "short_name":"Level     (Metres)",
               "subdesc":"",
               "variable":" 100.00",
               "units":"Metres",
               "name":"Stream Water Level"}
            }
          ]
        },
        "buff_supplied":8192}
      </s-gensym3>
    </JSonCallResponse>
  </soap:Body>
</soap:Envelope>

The SOAP web service may also be used for Hydstra systems with multiple DAT paths. The web portal must be correctly configured with a set of web userclasses with matching login credentials in the PASSWD table (the users' PASSWD:WEBUSERCLS fields must be populated).

To enable the web service to access the correct data, you must supply the username and password of the required userclass user as part of the SOAP request. There are several ways to do this in Perl (see ..\HYD\SYS\perl\examples\webservice.client.pl):

    my $buffersize = 1000000;
    my %parameters = (
      'function' => 'get_ts_traces',
      'version'  => 2,
      'params'   => {    
        'site_list'  => $siteid,
        'datasource' => 'A',
        'varfrom'    => '100.00',
        'varto'      => '100.00',
        'start_time' => $start,
        'end_time'   => $end,
        'data_type'  => 'mean',
        'interval'   => 'day',
        'multiplier' => '1'
      },
      'user'   => $username,
      'pass'   => $password,
    );
    Prt('-S', "\n\n", NowStr(), " - running JSonCall (proxy request Perl reference)\n", HashDump(\%parameters), "\n");
    my $json = SOAP::Lite
                -> uri($uri)
                -> proxy($proxy, options => {compress_threshold => 10000})
                -> JSonCall(\%parameters,$buffersize)
                -> result;
    Prt('-S', "returned JSON:\n", $json);

    # -----------------------------------------------------
    my $request_string = qq[{"function":"get_ts_traces",
      "version":2,
      "params":{
        "site_list":"$siteid",
        "datasource":"A",
        "varfrom":"100.00",
        "varto":"100.00",
        "start_time":"$start",
        "end_time":"$end",
        "data_type":"mean",
        "interval":"day",
        "multiplier":"1"
      },
      "user":"$username",
      "pass":"$password",
    }];
    Prt('-S', "\n\n", NowStr(), " - running JSonCall (proxy request string)\n$request_string\n");
    $json = SOAP::Lite
            -> uri($uri)
            -> proxy($proxy, options => {compress_threshold => 10000})
            -> JSonCall($request_string,$buffersize)
            -> result;
    Prt('-S', "returned JSON:\n", $json);

The REST web service may also optionally generate a naked JSON data structure by passing the parameter naked=1. The response would look like:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <JSonCallResponse xmlns="http://203.3.195.115/WebService">
      <s-gensym3 xsi:type="xsd:string">
        {
          "traces":[{
            "site_details":{
              "short_name":"Hydstra Test Station",
              "name":"Hydstra Test Station - Composite data"},
            "quality_codes":{
              "1":"Good continuous records"},
            "trace":[
              {"v":"0.363","t":19750801000000,"q":1},
              {"v":"0.368","t":19750802000000,"q":1},
              {"v":"0.363","t":19750803000000,"q":1},
              {"v":"0.464","t":19750804000000,"q":1},
              {"v":"0.505","t":19750805000000,"q":1},
              {"v":"0.417","t":19750806000000,"q":1},
              {"v":"0.368","t":19750807000000,"q":1},
              {"v":"0.318","t":19750808000000,"q":1},
              {"v":"0.294","t":19750809000000,"q":1},
              {"v":"0.285","t":19750810000000,"q":1},
              {"v":"0.308","t":19750811000000,"q":1},
              {"v":"0.461","t":19750812000000,"q":1},
              {"v":"0.507","t":19750813000000,"q":1},
              {"v":"0.457","t":19750814000000,"q":1},
              {"v":"0.396","t":19750815000000,"q":1},
              {"v":"0.369","t":19750816000000,"q":1},
              {"v":"0.354","t":19750817000000,"q":1},
              {"v":"0.344","t":19750818000000,"q":1},
              {"v":"0.328","t":19750819000000,"q":1},
              {"v":"0.275","t":19750820000000,"q":1},
              {"v":"0.251","t":19750821000000,"q":1},
              {"v":"0.243","t":19750822000000,"q":1},
              {"v":"0.237","t":19750823000000,"q":1},
              {"v":"0.228","t":19750824000000,"q":1},
              {"v":"0.222","t":19750825000000,"q":1},
              {"v":"0.221","t":19750826000000,"q":1},
              {"v":"0.267","t":19750827000000,"q":1},
              {"v":"0.349","t":19750828000000,"q":1},
              {"v":"0.300","t":19750829000000,"q":1},
              {"v":"0.254","t":19750830000000,"q":1},
              {"v":"0.231","t":19750831000000,"q":1},
              {"v":"0.220","t":19750901000000,"q":1}],
            "varfrom_details":{
              "short_name":"Level     (Metres)",
              "subdesc":"",
              "variable":" 100.00",
              "units":"Metres","name":"Stream Water Level"},
            "site":"HYDSYS01",
            "varto_details":{
              "short_name":"Level     (Metres)",
              "subdesc":"",
              "variable":" 100.00",
              "units":"Metres",
              "name":"Stream Water Level"}
            },
            {"site_details":{
               "short_name":"Hydstra Test Station",
               "name":"Hydstra Test Station - Secondary rainfall data"        },
             "quality_codes":{
               "1":"Good continuous records"},
             "trace":[
               {"v":"0.363","t":19750801000000,"q":1},
               {"v":"0.368","t":19750802000000,"q":1},
               {"v":"0.363","t":19750803000000,"q":1},
               {"v":"0.464","t":19750804000000,"q":1},
               {"v":"0.505","t":19750805000000,"q":1},
               {"v":"0.417","t":19750806000000,"q":1},
               {"v":"0.368","t":19750807000000,"q":1},
               {"v":"0.318","t":19750808000000,"q":1},
               {"v":"0.294","t":19750809000000,"q":1},
               {"v":"0.285","t":19750810000000,"q":1},
               {"v":"0.308","t":19750811000000,"q":1},
               {"v":"0.461","t":19750812000000,"q":1},
               {"v":"0.507","t":19750813000000,"q":1},
               {"v":"0.457","t":19750814000000,"q":1},
               {"v":"0.396","t":19750815000000,"q":1},
               {"v":"0.369","t":19750816000000,"q":1},
               {"v":"0.354","t":19750817000000,"q":1},
               {"v":"0.344","t":19750818000000,"q":1},
               {"v":"0.328","t":19750819000000,"q":1},
               {"v":"0.275","t":19750820000000,"q":1},
               {"v":"0.251","t":19750821000000,"q":1},
               {"v":"0.243","t":19750822000000,"q":1},
               {"v":"0.237","t":19750823000000,"q":1},
               {"v":"0.228","t":19750824000000,"q":1},
               {"v":"0.222","t":19750825000000,"q":1},
               {"v":"0.221","t":19750826000000,"q":1},
               {"v":"0.267","t":19750827000000,"q":1},
               {"v":"0.349","t":19750828000000,"q":1},
               {"v":"0.300","t":19750829000000,"q":1},
               {"v":"0.254","t":19750830000000,"q":1},
               {"v":"0.231","t":19750831000000,"q":1},
               {"v":"0.220","t":19750901000000,"q":1}],
             "varfrom_details":{
               "short_name":"Level     (Metres)",
               "subdesc":"",
               "variable":" 100.00",
               "units":"Metres",
               "name":"Stream Water Level"},
             "site":"HYDSYS02",
             "varto_details":{
               "short_name":"Level     (Metres)",
               "subdesc":"",
               "variable":" 100.00",
               "units":"Metres",
               "name":"Stream Water Level"}
            }
          ]
        }
      </s-gensym3>
    </JSonCallResponse>
  </soap:Body>
</soap:Envelope>

Sample Perl code for SOAP

A sample Perl script is provided to exercise several variants of SOAP requests at ..\HYD\SYS\perl\examples\webservice.client.pl

use strict;
use Compress::Zlib;
use SOAP::Lite;
#use SOAP::Lite 'trace', 'debug';
use JSON;
use CGI;
require 'hydlib.pl';

  sub urldecode {
    my $s = shift;
    $s =~ s/\%([A-Fa-f0-9]{2})/pack('C', hex($1))/seg;
    $s =~ s/\+/ /g;
    return $s;
  }

  main: {
    system('cls');

    my $domain  = 'realtimedata.water.nsw.gov.au';
    my $uri     = "http://$domain/WebService";
    my $proxy   = "http://$domain/cgi/webservice.pl";
    my $service = "http://$domain/wini/webservice.wsdl";
    my $query   = new CGI;
    print $query->header(-Accept_encoding => 'deflate');

    Prt('-S', NowStr(), " Started $0\n");
    Prt('-S', "domain: $domain\nuri: $uri\nproxy: $proxy\nservice: $service\n\n");

    # -----------------------------------------------------
    Prt('-S', NowStr(), " - running helloWorld (proxy)\n");
    my $return_string = SOAP::Lite
                     -> uri($uri)
                     -> proxy($proxy, options => {compress_threshold => 10000})
                     -> helloWorld
                     -> result;
    Prt('-S', "helloWorld returned [$return_string]\n\n");

    # -----------------------------------------------------
    Prt('-S', NowStr(), " - running helloWorld (wsdl)\n");
    $return_string = SOAP::Lite
                     -> service($service)
                     -> helloWorld;
    Prt('-S', "helloWorld returned [$return_string]\n");

    # -----------------------------------------------------
    my $buffersize = 1000000;
    my %parameters = (
      'function' => 'get_ts_traces',
      'version'  => 2,
      'params'   => {    
        'site_list'  => '201001',
        'datasource' => 'A',
        'varfrom'    => '100.00',
        'varto'      => '100.00',
        'start_time' => '19750501000000',
        'end_time'   => '19750510000000',
        'data_type'  => 'mean',
        'interval'   => 'day',
        'multiplier' => '1'
      }
    );
    Prt('-S', "\n\n", NowStr(), " - running JSonCall (proxy request Perl reference)\n", HashDump(\%parameters), "\n");
    my $json = SOAP::Lite
                -> uri($uri)
                -> proxy($proxy, options => {compress_threshold => 10000})
                -> JSonCall(\%parameters,$buffersize)
                -> result;
    Prt('-S', "returned JSON:\n", $json);

    # -----------------------------------------------------
    my $request_string = qq[{"function":"get_ts_traces",
      "version":2,
      "params":{
        "site_list":"201001",
        "datasource":"A",
        "varfrom":"100.00",
        "varto":"100.00",
        "start_time":"19750501000000",
        "end_time":"19750510000000",
        "data_type":"mean",
        "interval":"day",
        "multiplier":"1"
      }
    }];
    Prt('-S', "\n\n", NowStr(), " - running JSonCall (proxy request string)\n$request_string\n");
    $json = SOAP::Lite
            -> uri($uri)
            -> proxy($proxy, options => {compress_threshold => 10000})
            -> JSonCall($request_string,$buffersize)
            -> result;
    Prt('-S', "returned JSON:\n", $json);

    # -----------------------------------------------------
    Prt('-S', "\n\n", NowStr(), " - running JSonCall (wsdl request string)\n$request_string\n");
    $json = SOAP::Lite
             -> service($service)
             -> JSonCall($request_string,$buffersize);
    Prt('-S', "returned JSON:\n", $json);

    # -----------------------------------------------------
    $request_string = qq[%7B%22function%22%3A%22get_ts_traces%22%2C%22version%22%3A2%2C%22params%22%3A%7B%22site_list%22%3A%22201001%22%2C%22datasource%22%3A%22A%22%2C%22varfrom%22%3A%22100.00%22%2C%22varto%22%3A%22100.00%22%2C%22start_time%22%3A%2219750501000000%22%2C%22end_time%22%3A%2219750510000000%22%2C%22data_type%22%3A%22mean%22%2C%22interval%22%3A%22day%22%2C%22multiplier%22%3A%221%22%7D%7D];
    Prt('-S', "\n\n", NowStr(), " - running JSonCall (wsdl encoded request string)\n$request_string\n");
    $json = SOAP::Lite
             -> service($service)
             -> JSonCall($request_string,$buffersize);
    Prt('-S', "returned JSON:\n", $json);

    Prt('-S', "\n\n", NowStr(), " end\n\n");
  }

 

Sample WSDL (Webservices Description Language) file

Sample provided at \HYD\SYS\WDEF\wini\webservice.wsdl

Usually all you will need to amend are the URL domains at installation.

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="HydstraWebService"
             targetNamespace="http://127.0.0.1/WebService"
             xmlns="http://schemas.xmlsoap.org/wsdl/"
             xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
             xmlns:tns="http://127.0.0.1/WebService"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 
  <documentation>
    This web service enables SOAP data requests from the Hydstra water database of the [enter your organisation name here].
  </documentation>

  <message name="helloWorldRequest"/>
  <message name="helloWorldResponse">
    <part name="response" type="xsd:string"/>
  </message>
 
  <message name="JSonCallRequest">
    <part name="call" type="xsd:string"/>
  </message>
  <message name="JSonCallResponse">
    <part name="response" type="xsd:string"/>
  </message>
 
  <portType name="PortType">
    <operation name="helloWorld">
      <input message="tns:helloWorldRequest"/>
      <output message="tns:helloWorldResponse"/>
    </operation>
    <operation name="JSonCall">
      <input message="tns:JSonCallRequest"/>
      <output message="tns:JSonCallResponse"/>
    </operation>
  </portType>
  
  <binding name="Hydstra_Binding" type="tns:PortType">
    <soap:binding style="rpc"
                  transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="helloWorld" namespace="http://127.0.0.1/WebService">
      <soap:operation soapAction="http://127.0.0.1/WebService#helloWorld"/>
      <input>
        <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                   namespace="http://127.0.0.1/WebService"
                   use="encoded"/>
      </input>
      <output>
        <soap:body namespace="http://127.0.0.1/WebService"
                   encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                   use="encoded"/>
      </output>
    </operation>

    <operation name="JSonCall" namespace="http://127.0.0.1/WebService">
      <soap:operation soapAction="http://127.0.0.1/WebService#JSonCall"/>
      <input>
        <soap:body namespace="http://127.0.0.1/WebService"
                   encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                   use="encoded"/>
      </input>
      <output>
        <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                   namespace="http://127.0.0.1/WebService"
                   use="encoded"/>
      </output>
    </operation>
  </binding>
 
  <service name="HydstraWebService">
    <documentation>
      This web service enables SOAP data requests from the Hydstra water database of the [enter your organisation name here].
    </documentation>
    <port binding="tns:Hydstra_Binding" name="Hydstra_Port">
      <soap:address location="http://127.0.0.1/cgi/webservice.pl"/>
    </port>
  </service>
</definitions>

See Also

HYDLLP