Using PeopleCode to Manage Provider REST Service Operations

This section discusses how to:

• Read document template data and populate response messages.

• Set HTTP response headers.

• Retrieve HTTP response header data.

• Set server-side caching.

Reading Document Template Data and Populating Response Messages

To read document template data and populate provider response messages, use the OnRequest method. You implement the OnRequest method using an application class, specifically using the IRequestHandler application interface.

When the OnRequest event is fired the document template is populated with the values based on the corresponding URI template. You can use the populated primitive values along with the URI Template index to determine the proper response message data to send back to the client. The code snippet below shows a simple example of reading the document template data and populating the response message. Note that one can override the HTTP return code that is sent as part of the response to the client.

import PS_PT:Integration:IRequestHandler;

class WeatherData implements PS_PT:Integration:IRequestHandler
   method WeatherData();
   method OnRequest(&MSG As Message) Returns Message;
   method OnError(&request As Message) Returns string;
end-class;

/* constructor */
method WeatherData
end-method;

method OnRequest
   /+ &MSG as Message +/
   /+ Returns Message +/
   /+ Extends/implements PS_PT:Integration:IRequestHandler.OnRequest +/
   /* Variable Declaration */
   Local Document &Doc;
   Local Compound &COM;
   Local Message &response;
   Local XmlDoc &weather_xmldoc;
   Local XmlNode &info, &country, &state, &city, &day, &data, &flightdata;
   Local Rowset &RS;
   /* get populated Document Template */
   &Doc = &MSG.GetURIDocument();
   &COM = &Doc.DocumentElement;
   &weather_xmldoc = CreateXmlDoc("");
 /* populate xmldoc with data from the Document Template */
   &info = &weather_xmldoc.CreateDocumentElement("WeatherInformation");
   &country = &info.AddElement("Country");
   &country.NodeValue = &COM.GetPropertyByName("country").Value;
   &state = &info.AddElement("State");
   &state.NodeValue = &COM.GetPropertyByName("state").Value;
   &city = &info.AddElement("City");
   &city.NodeValue = &COM.GetPropertyByName("city").Value;
   &day = &info.AddElement("Day");
   &day.NodeValue = &COM.GetPropertyByName("day").Value;
/*  determine HTTP method that was invoked to determine proper response 
/*  message */   
   If &MSG.HTTPMethod = %IntBroker_HTTP_GET Then
      &data = &info.AddElement("Forecast");
      &data.NodeValue = "55 degrees and raining";
      &response = CreateMessage(Operation.WEATHERSTATION_GET, 
        %IntBroker_Response);
      &response.SetXmlDoc(&weather_xmldoc);
   End-If;
   If &MSG.HTTPMethod = %IntBroker_HTTP_DELETE Then
      &data = &info.AddElement("Forecast");
      &data.NodeValue = "deleted";    
      &response = CreateMessage(Operation.WEATHERSTATION_DELETE, 
        %IntBroker_Response);
      &response.SetXmlDoc(&weather_xmldoc);
   End-If;
   Return &response;  
end-method;

method OnError
   /+ &request as Message +/
   /+ Returns String +/
   /+ Extends/implements PS_PT:Integration:IRequestHandler.OnError +/
   Local Message &Fault_Msg;
   Local Document &fault_doc;
   Local Compound &COM;
   If &request.HTTPMethod = %IntBroker_HTTP_GET Then
      &Fault_Msg = CreateMessage(Operation.WEATHERSTATION_GET, 
        %IntBroker_Fault);
      &fault_doc = &Fault_Msg.GetDocument();
      &COM = &fault_doc.DocumentElement;
      &COM.GetPropertyByName("fault_data").Value = &request.IBException.
        ToString();
      Return &fault_doc.GenXmlString();
   End-If;
   Return "";
end-method;

Setting HTTP Response Headers

Use the LoadRESTHeaders method of the IBInfo class to load the response headers defined on the routing for a REST-based service operation. Once loaded, the headers can be modified without specifying the connector override property.

The code snippet below shows how to add HTTP response headers to the any REST based service operation response within the OnRequest event.

&response = CreateMessage(Operation.WEATHERSTATION_GET, %IntBroker_Response);
&bRet =   &response.IBInfo.LoadRESTHeaders();  

/* any/ modify additional Headers not defined on Routing */
&bRet = &response.IBInfo.IBConnectorInfo.AddConnectorProperties
    ("Content-Language ", "eng ", %HttpHeader);
Return &response;

Retrieving Response HTTP Header Data

You can use the REST method type Head to retrieve meta-information written in response HTTP headers, without having to transport the entire content.

The REST-based service operation created with a method of HEAD does not have a request or response message.

You can assign the OnRequest handler used for the GET method to the service operation to check if the method type is HEAD and, if so, simply send back the HTTP response headers.

The following code snippet shows how to use the OnRequest method to retrieve HTTP response headers

Note:

HTTP response headers can be sent back to the client for all REST method types.

If &MSG.HTTPMethod = %IntBroker_HTTP_HEAD Then

&response = CreateMessage(Operation.WEATHERSTATION_HEAD, 
  %IntBroker_Response);
&bRet =   &response.IBInfo.LoadRESTHeaders();  

/* any additional Headers not defined on Routing */
&bRet = &response.IBInfo.IBConnectorInfo.AddConnectorProperties
 ("Content-Language ","eng ", %HttpHeader);

&bRet = &response.IBInfo.IBConnectorInfo.AddConnectorProperties
 ("WWW-Authenticate", "Basic",  %HttpHeader);
Return &response;
End-If;

Setting Server-Side Caching

For provider REST GET service operations you can set server-side caching by setting the SetRESTCache method on the Message object in the OnRequest PeopleCode event. The SetRESTCache method takes a future Date Time object.

If you set server-side caching the system caches the entire transactional data for the specific URI resource. Subsequent requests from a client with an identical resource will result in the data being pulled from memory/file cache.

At any time you can delete the cache by calling the DeleteRESTCache method on the IntBroker PeopleCode object. The DeleteRESTCache method takes the service operation and service operation version as input variables.