EGL REST API On Application Servers

Content

Introduction

The REST web services can be invoked using HTTP. The service provides access to a web resource specified in a URI. The service's operations correspond to HTTP operations, four of which are supported in EGL: 

• GET – This service retrieves the resources.
• POST – This service creates the resources.
• PUT – This service creates or updates the resources.
• DELETE – This service deletes the resources.

EGL provides a common framework for applications to be available as REST web services. This framework has the following three components:

1. An EGL service part: It describes the operations made available with REST and the passed parameters.
2. An EGL Deployment Descriptor: It describes how to deploy the EGL REST service to a target platform.
3. The EGL serviceLib Library: It provides a set of functions for customizing and processing the REST invocation and response.

In EGL, a REST service’s URI is split into two components:

1. A base URI: It is the leading part of the URI and is usually the address of the REST service.
2. A URI template: It is the trailing part of the URI and usually contains the service's name and parameters.

At run time, the base URI and URI template are concatenated to form the complete URI for invocation, which means it is also possible to have the full URI in either the base URI or the URI template. For example, if a REST service has a URI as follows:

http://www.example.com/myservice?q={myquery}&numReturnRows={rowCount}

Then the base URI is http://www.example.com and the URI template is /myservice?q={myquery}&numReturnRows={rowCount}.

Note: The myquery and rowCount are the parameters whose values are substituted at run time.

Prerequisites

• IBM Rational Business Developer (RBD).
• An application server such as Apache Tomcat or IBM WebSphere.
• Knowledge of developing services using EGL and RBD.
• Knowledge of OpenAPI/Swagger documentation.
   

EGL Annotations for REST Services

Functions in an EGL Service are mapped to a REST operation using the @Rest annotation. The following four types of @Rest annotations are available, which correspond to the four primary REST operations:

• @GetRest
• @PutRest
• @PostRest
• @DeleteRest

Figure 1 shows an example of an EGL Service that can be used to invoke a REST service. In this example, the service is called service1, and it operates on a web resource described by the record employee. The value of the parameter empno is used to create the full URI needed to invoke the REST operation GET (EGL getEmployee function). You can use any number of parameters in the uriTemplate. Still, only a maximum of one parameter can be used as the resource representation, which is sent to and received from the REST service. This parameter is placed in the body of the HTTP request and response. For this example, we are sending and receiving emp as the representation resource.

package services;

record employee type sqlrecord{description = "everything you need to know about an employee", tableNames =[["SAMP.EMPLOYEE"
                    ]], fieldsMatchColumns = yes, keyItems =[empno]}

    empno string{column = "EMPNO", maxLen = 6};
    firstnme string{column = "FIRSTNME", sqlVariableLen = yes, maxLen = 12};
    midinit string{column = "MIDINIT", maxLen = 1};
    lastname string{column = "LASTNAME", sqlVariableLen = yes, maxLen = 15};
    workdept string{column = "WORKDEPT", isSqlNullable = yes, maxLen = 3};
    phoneno string{column = "PHONENO", isSqlNullable = yes, maxLen = 4};
    hiredate date{column = "HIREDATE", isSqlNullable = yes, description = "employee's hire date"};
    job string{column = "JOB", isSqlNullable = yes, maxLen = 8};
    edlevel smallInt{column = "EDLEVEL"};
    sex string{column = "SEX", isSqlNullable = yes, maxLen = 1};
    birthdate date{column = "BIRTHDATE", isSqlNullable = yes};
    salary decimal(9, 2){column = "SALARY", isSqlNullable = yes};
    bonus decimal(9, 2){column = "BONUS", isSqlNullable = yes};
    comm decimal(9, 2){column = "COMM", isSqlNullable = yes};
end

service service1{Title = "Employee Service", description = "Operates On The Employee Database", version = "1.0.0"}

    function getEmployee(empno string in) returns(employee){tags =[
                        "employeeRecord", "retrieveEmployee"
                ], description = "gets an existing employee", @GetRest{uriTemplate = "/employee/{empno}", responseFormat = JSON}}

        myemp employee;
        myemp.empno = empno;
        get myemp;
        if(myemp is norecordfound)
            nfresp HttpResponse;
            nfresp.status = 404;
            nfresp.body = "Employee " + empno + " Not Found";
            serviceLib.setRestResponse(nfresp);
        end
        return(myemp);

    end

    function addEmployee(emp employee in){tags =["employeeRecord",
                        "modifyEmployee"
                ], description = "adds a new employee", @PostRest{uriTemplate = "/newemployee", requestFormat = JSON}}

        add emp;
    end

    function updateEmployee(emp employee in){tags =["employeeRecord",
                        "modifyEmployee"
                ], description = "updates an existing employee", @PutRest{uriTemplate = "/changeemployee", requestFormat = JSON}}

        replace emp noCursor;
        if(emp is norecordfound)
            nfresp HttpResponse;
            nfresp.status = 404;
            nfresp.body = "Employee " + emp.empno + " Not Found";
            serviceLib.setRestResponse(nfresp);

        end

    end

    function deleteEmployee(empno string in){tags =["employeeRecord",
                        "modifyEmployee"
                ], description = "deletes an existing employee", @DeleteRest{uriTemplate = "/removeemployee/{empno}"}}

        myemp employee;
        myemp.empno = empno;

        delete myemp noCursor;
        if(myemp is norecordfound)
            nfresp HttpResponse;
            nfresp.status = 404;
            nfresp.body = "Employee " + empno + " Not Found";
            serviceLib.setRestResponse(nfresp);

        end
    end

end

Figure 1 An Example Service with REST API

Each of the @Rest annotations has the following three properties:

1. uriTemplate

   This property allows the user to parameterize the URI. Each parameter in the URI corresponds to a parameter defined in the function. At run time, the values of the parameters are substituted into the URI, which is then appended to the base URI to create the full URI needed to invoke the service.

2. requestFormat

   This property specifies how the to format the request data when sent to the REST service. The following three formats are available in EGL:

   • NONE – the request data is sent as a string.
   • XML – the request data is an EGL record, which is converted to XML at run time..
   • JSON – the request data is an EGL record, which is converted to JSON at run time.
3. responseFormat

   This property specifies the format that the REST service uses to send back data. The following three formats that the EGL can understand:

   • NONE – The response data is a raw string that is sent to the EGL client as-is.
   • XML – The response data is an XML formatted string that is to be converted to an EGL record.
   • JSON – The response data is a JSON formatted string that is to be converted to an EGL record.
      

Documenting the REST Service

EGL provides additional annotations for documenting REST Services. This is used to generate the OpenAPI document that defines the REST Service. The OpenAPI document includes the following:

• Title

Title of the OpenAPI document.

• Description

A brief description of the service, operation, or record.

• Version

A user-defined version number of the service.

• Tags

Allows the service operations to be grouped by keyword(s) in the OpenAPI document.

Refer to the Figure 1 for examples.

Preferences for Documenting the REST Service

Default values for generating OpenAPI documentation are provided on the EGL Services page in the Preferences (refer to Figure 2).

Figure 2: Preferences for OpenAPI Generation

Host Name and Port are used to customize the server URL listed in the OpenAPI document.

Note: Port 8080 should be specified here for Tomcat deployment, as this is the default port used by Tomcat.

OpenAPI Version controls the format of the generated OpenAPI document. The default is OpenAPI-3.0, but you can also select OpenAPI-2.0 (also known as the Swagger specification).

Specifying Service Deployment in the Deployment Descriptor

To deploy the EGL Service as a REST service, specify the Service Deployment in an EGL Deployment Descriptor as follows:

1. Open the EGL Deployment Descriptor for your project.
2. Go to the Service Deployment tab and click Add.
3. Select REST Service under Generate as.
4. Add the EGL Service you wish to deploy as a REST service and click ‘Finish.’

Note: If required, set the URI under REST Web Service Properties. This is the base URI that the service will be available. The default value is the service name. The URI template is appended, as shown in the example below, to create the invocable URI. http://localhost:8080/ServiceTomcat/api/service1/employee/{empno}

Figure 3: Adding a REST Service Deployment.

Figure 4: Rest Service Deployment

Deploying EGL REST Service

To deploy the EGL Service to an application server, specify the deployment target as an Eclipse Dynamic Web Project as follows:

1. Open the EGL Deployment Descriptor for your project.
2. Go to the Overview tab, and set the Deployment Target to be an Eclipse Dynamic Web Project.
3. Right-click on the deployment descriptor, and select Deploy EGL Descriptor.

Figure 5: Deployment Target for EGL REST Deployment

The generated Java for the EGL service will be deployed to the target web project, along with wrapper artifacts that will allow you to run the EGL Service as a JAXRS REST service (See Figure 6).

Figure 6: Deployable Artifacts

Running EGL REST Services

Start the application server in the Servers tab and the EGL REST Service will start automatically.

Invoking The EGL Service

The URL and other information needed to invoke the service are provided in the generated OpenAPI document (refer to service1.json in Figure 6). Figure 6 shows an example with Swagger Editor.

Note: The documentation annotations shown in Figure 1 are used to format this presentation. For example, all the operations tagged with ‘employeeRecord’ are grouped together.

The invocation URL is provided by the Servers block (REST API Endpoint), and the paths for each operation are appended to this (refer to Figure 7).

Figure 7: OpenAPI Document in Swagger Editor

Customizing The Service Response

The system function serviceLib.setRestResponse allows an EGL Java REST Service to set a custom HTTP response depending on the business logic. Otherwise, the default response is 200 OK (along with the service function’s return data) or 500 Internal Server Error (for unhandled exceptions). Refer to Figure 1 for an example of this function.

Syntax

serviceLib.setRestResponse(response HttpResponse in)

The invocation sets the REST HTTP response using the Record part HttpResponse, which is provided for you and has the following fields:

• body, type STRING
  The response body to be returned from the service;
• body contains the value in one of three formats (XML, JSON, or NONE), as described in REST for the developer
  • If the body is not specified, then the value of the body will be the function response in one of three formats (XML, JSON, or NONE)
• headers, type Dictionary
  headers contain a set of name-value pairs. Each entry key in the dictionary is the name of an HTTP header that is to be returned from the service, and the related value (a string) is the value of that header.
• status, type INT
  status contains the HTTP status code for the response. If the status is not specified, then the value 200 is used.
  Important status codes include 200 (OK) and 404 (Not Found). For a complete list, go to the website of the World Wide Web Consortium (http://www.w3.org/) and search for "HTTP status code.".
• statusMessage, type STRING
  statusMessage contains the HTTP status message for the response. If statusMessage is not specified, then the value OK is used.
  Important status messages include OK (code 200) and Not Found (code 404). For a complete list, go to the World Wide Web Consortium's website (http://www.w3.org/) and search for "HTTP status code."