Standard Request Response DTO Pattern - AquaticInformatics/aquarius-sdk-net GitHub Wiki

var request = new RequestDTO {Property1 = value1, Property2 = value2};
var response = client.EndPoint.Verb(request);

This is the pattern you will find yourself using over and over again as you consume the AQTS APIs:

  • Create a request DTO object, setting only the properties you care about
  • Invoke the appropriate HTTP Verb (GET/POST/DELETE/etc.) on the appropriate public API endpoint (Publish, Provisioning, Acquisition)
  • Parse the returned response DTO as needed to get your results.
  • If an error occurs, a WebServiceException will be thrown. See the Error Handling wiki for details

Every AQTS public REST API follows a Message-Based Web Service pattern. A request DTO (Data Transfer Object) captures all of the request parameters and a corresponding response DTO captures all of the response properties.

The Aquarius.Client assembly and its dependencies handle all the JSON serialization/deserialization work, as well as all the HTTP request composition housekeeping of URL-encoding and path template substitution. As a result, your client code just deals with DTO objects.

All the public properties of DTOs have default values (0 for numeric data types, null for strings or object types). If your code does not need to change a default request property, then there is no need to explicitly set it. This often results in very concise, wrist-friendly code.

The Aquarius.Client.dll assembly includes a request and response DTO service model definition for every operation on every public API endpoint. The names of the DTOs correspond to the names of the DTOs listed on the Metadata Operations page of each endpoint.

Getting the list of time-series at a known location

To find all the time-series at a location with an identifier of "TheRiver", you would issue a GET http://yourserver/AQUARIUS/Publish/v2/GetTimeSeriesDescriptionList?LocationIdentifier=TheRiver request.

The Publish API Metadata Operations page lists the TimeSeriesDescriptionServiceRequest operation in details.

Expressed in code, this would be:

using Aquarius.TimeSeries.Client;
using Aquarius.TimeSeries.Client.ServiceModels.Publish;
...
var request = new TimeSeriesDescriptionServiceRequest {LocationIdentifier = "TheRiver"};
var response = client.Publish.Get(request);

Console.WriteLine($"There are {response.TimeSeriesDescriptions.Count} time-series at {request.LocationIdentifier}");