Walkthrough the REST Samples in ENSDEMO

The Demo.REST.DirectoryService implements a REST service that provides access to a Caché database provided in the SAMPLES namespace.

In order to call a REST service using the CSP port, you must first define a web application to handle the class of the service. For example, to call the Demo.REST.MathService or the Demo.REST.DirectoryService in ENSDEMO, you could define a web application named /RestServices in the ENSDEMO namespace. You must allow access to the ENSDEMO database and the SAMPLES database. See “Configuring Ensemble for REST Services” for a walkthrough of configuring Ensemble and defining a web application.

If you are running Demo.Rest.Production, then you can enter following REST call in a web browser. This sends an HTTP GET request that queries for the people in the database whose name begins with “j”:

http://localhost:57772/RestServices/Demo.REST.DirectoryService/directory/person/name/j*

The browser sends this URL as an HTTP Get command. The URLMap sends this request to the retrievePerson method with the following parameters:

retrievePerson("person","name","j*")

This method builds an SQL query statement that requests the information from the SAMPLES database and executes the query. It then calls the ObjectToJSONStream() method and returns the following JSON to the REST caller:

[{
    "Age":38,
    "Company":"InterTron Holdings Inc.",
    "DOB":"1975-06-05",
    "FavoriteColors":,
    "Home": {
        "City":"Islip",
        "State":"WY",
        "Street":"1199 Maple Place",
        "Zip":38998
    },
    "ID":179,
    "Name":"Jung,Jules G.",
    "Office": {
        "City":"Youngstown",
        "State":"OH",
        "Street":"803 Madison Place",
        "Zip":70937
    },
    "SSN":"584-94-9346",
    "Spouse":"Underman,Diane Z."
},{
    "Age":24,
    "Company":"MacroNet Associates",
    "DOB":"1989-06-05",
    "FavoriteColors":["Black","Purple"
    ],
    "Home": {
        "City":"Jackson",
        "State":"VT",
        "Street":"9371 Elm Drive",
        "Zip":93057
    },
    "ID":186,
    "Name":"Jung,Sam B.",
    "Office": {
        "City":"Gansevoort",
        "State":"SD",
        "Street":"6284 First Place",
        "Zip":84332
    },
    "SSN":"173-48-2772",
    "Spouse":"Fripp,Hannah D."
}]

Although you can create an HTTP GET command by just entering a URL in a browser, it is harder to generate an HTTP POST, PUT, or DELETE. You can use a utility such as curl to generate these HTTP commands or you can use the DirectoryPage and DirectoryOperation provided in the ENSDEMO REST sample. Since the DirectoryOperation calls the REST service from the Ensemble DirectoryService, it is not an ideal example showing how to call an external REST service, but it is a very useful tool to demonstrate calling the DirectoryService REST services.

To use the DirectoryPage and Directory Operation, in Studio select the ENSDEMO namespace and open the class Demo.REST.DirectoryPageOpens in a new tab. Select View Web Page and Studio displays the following web page in your default browser:

If you enter j* as the Key Value and click Retrieve, the web page and DirectoryOperation sends the same HTTP GET command that you entered in the browser. The web page displays the URL sent to the DirectoryService and the JSON returned by it. The page displays a table with two columns from the returned data. If you click on one of the rows, the page displays all of the properties and values for that person. You can then alter some of the values and click Update, which generates an HTTP POST command. If you click Delete, it deletes the record with the specified ID value with an HTTP DELETE command. Finally if you update the SSN field with a unique value and click Create, it creates a new record with an HTTP PUT command.

The DirectoryPage web page displays the JSON value returned by DirectoryService but does not display any JSON values sent to the service. One way to view these values is to use a TCP trace utility. Simply modify the DirectoryOperation configuration page to specify another port, such as 9989 and then use the TCP trace utility to transfer the message from port 9989 to 9988.

Remember, if you use this page to update the data, you are changing the data in the Caché SAMPLES database.

It is also possible to not use URLMap and implement the lower-level OnProcessInput() method. The following shows to process the call in this method:

Class Demo.REST.DirectoryService Extends EnsLib.REST.Service
{

Parameter ADAPTER = "EnsLib.HTTP.InboundAdapter";

/// The EnsServicePrefix parameter identifies the URL prefix that this component handles
Parameter EnsServicePrefix = "/directory";

Method OnProcessInput(
    pInput As %Library.AbstractStream,              /// Contains the HTTP command
    Output pOutput As %Stream.Object) As %Status    /// Output to return to REST call
  {
   /// Get the HTTP operation: GET, POST, PUT, or DELETE
   Set tCmd=$ZConvert(pInput.Attributes("HttpRequest"),"U")

   /// Get the URL
   Set tURL=$ZConvert(pInput.Attributes("URL"),"I","URL")

   /// Get the 2nd part of the URL which contains the service,
   /// Test that it matches EnsServicePrefix, "/directory"
   Set tService="/"_$ZConvert($Piece(tURL,"/",2),"L")  Quit:..#EnsServicePrefix'=tService

   /// Get the 3rd part of the URL either person or employee
   Set tType=$ZConvert($Piece(tURL,"/",3),"L") 

   /// Get the 4th part of the URL in this case name
   Set tKeyIn=$Piece(tURL,"/",4), tKey=$ZConvert(tKeyIn,"L")

   /// Get the 5th part of the URL, the value to query for
   Set tKeyVal=$Replace($ZConvert($Piece(tURL,"/",5),"I","URL"),"'","''")