A WebHandler is a custom ABL class that inherits the OpenEdge.Web.WebHandler class and contains methods that enable you to handle REST requests.

You use a WebHandler in a WEB transport service that you create. When you create the service, you define a list of URIs that get associated with the WebHandler. At runtime, when a client application makes a request to a URI, the request is passed to the associated WebHandler and processed by a method that corresponds to the HTTP verb used in the request (GET, PUT, POST, or DELETE).

Overview of steps to use a WebHandler

You perform the following steps to use a WebHandler:
  1. Create a user-defined class which inherits from OpenEdge.Web.WebHandler class.
  2. Implement methods to handle requests.
  3. Create a WEB transport service.

Create a WebHandler class

Perform the following steps to create a WebHandler class file:
  1. In OpenEdge Developer Studio, right-click the root project folder and select New > WebHandler.
  2. In the New WebHandler dialog box, enter a name for the WebHandler class, select the method stubs that you want to create, and click Finish.
    Note:
    • Method stubs in the New WebHandler wizard correspond to HTTP REST methods. You must, at a minimum, select the GET method.
    • The Package root field defines the location for the WebHandler class. While the WebHandler can be stored in any location accessible to the ABL application's PROPATH, we recommend retaining the default location, which is /PASOEContent/WEB-INF/openedge in the root project directory.

Implement methods to handle requests

To implement methods in the WebHandler, open the WebHandler class file (the default location is /PASOEContent/WEB-INF/openedge).

What method stubs are generated

Method stubs in the WebHandler class are created with the prefix Handle (HandleGet(), HandlePut(), etc). In addition to method stubs of your choice, stubs are created for two methods—HandleNotAllowed() and HandleNotImplemented() to enable you to handle unsupported requests.

How to pass requests to business logic

Each method stub takes one input parameter—an OpenEdge.Web.IWebRequest object with the default name poRequest. This input parameter represents the client application's request message and is automatically passed to the method at runtime, based on the request's HTTP method.

You can perform various types of operations on this request object within a method. For example, you can extract path parameter values from the object, pass the values to an ABL class that contains business logic, etc.
METHOD OVERRIDE PROTECTED INTEGER HandleGet( INPUT poRequest AS OpenEdge.Web.IWebRequest ):
   ...
   ...        
   DEFINE VARIABLE CustomerName AS CHARACTER NO-UNDO.
   DEFINE VARIABLE Customer AS Customer.
   Customer = NEW Customer().
   CustomerName = Customer:getCustomerName(poRequest:GetPathParameter("custid")).
    

END METHOD.
Note: For more information on available OpenEdge.Web.WebHandler methods, see OpenEdge.Web.WebHandler.
How to return a response
To return a response, you perform two steps:
  • Construct an OpenEdge.Web.WebResponse object using the IHttpResponse interface to build a response message with headers, status code, body, etc.
    METHOD OVERRIDE PROTECTED INTEGER HandleGet( INPUT poRequest AS OpenEdge.Web.IWebRequest ):

  ...
  ...
  DEFINE VARIABLE oResponse AS OpenEdge.Net.HTTP.IHttpResponse NO-UNDO.
  DEFINE VARIABLE oWriter   AS OpenEdge.Web.WebResponseWriter  NO-UNDO.
  DEFINE VARIABLE oBody     AS OpenEdge.Core.String            NO-UNDO.
  ...

  CustomerName = Customer:getCustomerName(poRequest:GetPathParameter("custid")).
  ASSIGN 
     oResponse            = NEW OpenEdge.Web.WebResponse()
     oResponse:StatusCode = INTEGER(StatusCodeEnum:OK)
     .
  ASSIGN 
      oBody = NEW OpenEdge.Core.String(CustomerName).            
  ASSIGN 
      oResponse:Entity        = oBody
      oResponse:ContentType   = 'application/json':u
      oResponse:ContentLength = oBody:Size
      .
       

END METHOD.
  • Pass the WebResponse object to a WebResponseWriter() and call Open() and Close() on it.
    ASSIGN 
        oWriter = NEW WebResponseWriter(oResponse).
        oWriter:Open().
        oWriter:Close().

Examples

These examples show how to use a WebHandler to address common use cases.
How to get a path parameter value
A path parameter is a segment in the request URI. A path parameter can be a variable. In this example, the number 2 at the end of the URI is a customer ID.
http://MyAppServerHost:8810/SportsApp/web/CustomerService/Customer/2

To get a path parameter value, pass the parameter name to the GetPathParameter() method. 

CustomerName = Customer:getCustomerName(poRequest:GetPathParameter("custid")).
For this to work, the path parameter name (custid) must be specified in the list of URIs handled the WEB transport service (see the section Create a WEB transport service).
How to get a query parameter value
A query parameter is a query specified in the request URI. Here is an example of a customer ID passed as a query parameter:
http://MyAppServerHost:8810/SportsApp/web/CustomerService/Customer?custid=2
To get a query parameter value, use GetContextValue("QUERY_STRING"). This returns a string containing the query. If there are multiple queries, joined by the '&' symbol (for example custid=2&orderid=2) you get all the queries in a single string. You can extract values from the query parameters as shown in this example:
DEFINE VARIABLE cQryString AS CHARACTER NO-UNDO.
cQryString = STRING(poRequest:GetContextValue("QUERY_STRING")).

DEFINE VARIABLE cPair AS CHARACTER NO-UNDO.
DEFINE VARIABLE ix AS INTEGER   NO-UNDO.
DEFINE VARIABLE cKey AS CHARACTER NO-UNDO.
DEFINE VARIABLE cValue AS CHARACTER NO-UNDO.
REPEAT ix = 1 TO NUM-ENTRIES(cQryString,'&'):
   cPair = ENTRY(ix,cQryString,'&').
   cKey = ENTRY(1,cPair,'=').
   cValue = ENTRY(2,cPair,'=').
   oWriter:Write("query string pair: " + cKey + " / " + cValue + "<br
      />").
END.
How to get headers
To get the value of a header by the header name:
poRequest:GetHeader("User-Agent"))

Create a WEB transport service

A WEB transport service is an ABL service that uses the WEB transport and a WebHandler to process requests. It contains a list of URIs that are handled by the WebHandler. When a client application makes a request to a URI in the service, the WebHandler that is associated with the service handles the request.

Perform the following steps to create a WEB transport service:

  1. Right-click the project in OpenEdge Developer Studio and select New > ABL Service.
  2. In the New ABL Service wizard:
    • Choose WEB as the transport.
    • Enter a name for the service.
    • Choose Select existing and specify the WebHandler class that you want to associate with the service. The Browse button enables you to search for existing WebHandlers, including those that you created.
    • Specify URIs that will be handled by the service by clicking the Add button in the Resource URIs section. Specify variable path parameters by enclosing them in curly braces (for example {custid}).
      The order of Resource URI(s) values matters. The algorithm uses the first available match, so the more specific match must be higher on the list.
      Note: The Resource URI(s) may include regular expressions as part of the path parameters. For a complete list of regular expressions in the path parameter, see regex.