Developing a REST Operation

To develop a REST operation, you extend the class EnsLib.REST.OperationOpens in a new tab. The REST operation uses Ensemble’s outbound HTTP adapter, which is described in Using the HTTP Outbound Adapter.

Using the HTTP Outbound Adapter, you specify the server, port, and address of the external web service in the HTTP adapter configuration. For example, to define a REST operation that calls a weather service, you could configure the operation as follows:

generated description: operation weather

In your extension of EnsLib.REST.OperationOpens in a new tab, you specify the remaining parts of the URL by appending the value to the adapter URL property. Then you call one of the following adapter methods depending on what HTTP operation you want to use:

GetURL()—uses the HTTP GET operation.
PostURL()—uses the HTTP POST operation.
PutURL()—uses the HTTP PUT operation.
DeleteURL()—uses the HTTP DELETE operation.
SendFormDataArray()—allows you to specify the HTTP operation as a parameter.

For example, the following extension of EnsLib.REST.OperationOpens in a new tab calls the weather REST service and provides a city name as a parameter:

Class Test.REST.WeatherOperation Extends EnsLib.REST.Operation
{

Parameter INVOCATION = "Queue";

Method getWeather(
   pRequest As Test.REST.WeatherRequest,
   Output pResponse As Test.REST.WeatherResponse) As %Status
{
   
   try {
      // Prepare and log the call
      // Append the city to the URL configured for adapter
      Set tURL=..Adapter.URL_"?q="_pRequest.City_"&units=imperial"
      
      // Execute the call
      Set tSC=..Adapter.GetURL(tURL,.tHttpResponse)
      
      // Return the response
      If $$$ISERR(tSC)&&$IsObject(tHttpResponse)&&$IsObject(tHttpResponse.Data)&&tHttpResponse.Data.Size {
         Set tSC=$$$ERROR($$$EnsErrGeneral,$$$StatusDisplayString(tSC)_":"_tHttpResponse.Data.Read())
      }
      Quit:$$$ISERR(tSC)
      If $IsObject(tHttpResponse) {
         // Instantiate the response object
         set pResponse = ##class(Test.REST.WeatherResponse).%New()
         // Convert JSON into a Proxy Cache Object
         set tSC = ..JSONStreamToObject(tHttpResponse.Data, .tProxy)
         if (tSC){                                 
            // Set response properties from the Proxy Object
            set pResponse.Temperature = tProxy.main.temp_"F"
            set pResponse.Humidity = tProxy.main.humidity_"%"
            set pResponse.MaxTemp = tProxy.main."temp_max"_"F"
            set pResponse.MinTemp = tProxy.main."temp_min"_"F"
            set pResponse.Pressure = tProxy.main.pressure_" mbar"
            set pResponse.WindSpeed = tProxy.wind.speed_" MPH"
            set pResponse.WindDirection = tProxy.wind.deg_" degrees"
            // Convert from POSIX time
            set pResponse.Sunrise = $ZT($PIECE($ZDTH(tProxy.sys.sunrise, -2),",",2),3)
            set pResponse.Sunset = $ZT($PIECE($ZDTH(tProxy.sys.sunset, -2),",",2),3)
          }
       }
   }catch{
       Set tSC=$$$SystemError
   }
   Quit tSC
}

XData MessageMap
{

<MapItems>
  <MapItem MessageType="Test.REST.WeatherRequest">
    <Method>getWeather</Method>
  </MapItem>
</MapItems>
}

}

The message sent to the operation specifies the city:

Class Test.REST.WeatherRequest Extends (%Persistent, Ens.Util.MessageBodyMethods)
{
   Property City As %String;
}

This operation calls the JSONStreamToObject() method and returns a Caché object that makes the elements of the JSON accessible. The message returned by this sample returns the following properties taken from the JSON stream:

Class Test.REST.WeatherResponse Extends (%Persistent, Ens.Util.MessageBodyMethods)
{
   Property Temperature As %String;
   Property MinTemp As %String;
   Property MaxTemp As %String;
   Property Pressure As %String;
   Property Humidity As %String;
   Property WindSpeed As %String;
   Property WindDirection As %String;
   Property Sunrise As %String;
   Property Sunset As %String;
 }

If you don’t have a business process running you can run and test this and other operations on the Production Configuration page by selecting your operation, navigating to Actions in the Production Settings menu and clicking Test.