EGL Support For REST

EGL Services can be invoked by REST calls using two different methods

RPC call that is made over HTTP, using the POST method. This is known as EGL REST RPC. This is suitable for EGL Service functions with multiple input and output parameters.
REST API calls using HTTP methods GET, POST, PUT, DELETE. This is suitable for EGL Service functions that provide access to a resource, such as database records.

Service part for EGL REST-RPC

This example shows a Service part for an EGL REST-RPC service. The example includes a single function:

Service EmployeeService
   Function GetEmployeeDetail(employeeCode STRING IN, 
                              employeeSalary FLOAT OUT, 
                              employeeStatus STRING INOUT) 
            returns(myEmployeeRecordPart)
	//service logic
	end
end

User can specify various EGL data types and can use the modifiers IN, OUT, and INOUT.

Non_EGL Clients wishing to invoke this service must use the EGL REST RPC message format as described in EGL REST-RPC message structure. EGL clients can use the service with a standard EGL function call, as described in Declaring a variable to access a REST service

Service part for REST API

This example shows a Service part for an EGL REST service:

Service EmployeeService
   Function GetEmployeeDetail(employeeCode STRING IN) 
            returns(myEmployeeRecordPart)
      {@GetRest{uriTemplate="/employee?code={employeeCode} }",
                requestFormat = JSON,
                responseFormat = JSON}};
	//service logic
	end
end

To access EGL services via REST API, user must specify a complex property for each function. The name of the property indicates the HTTP verb that is used to access the service:

For the GET method, the property name is @GetREST.
For the POST method, the property name is @PostREST.
For the PUT method, the property name is @PutREST.
For the DELETE method, the property name is @DeleteREST.

Those complex properties are called the @xREST properties because the same three property fields are in each, as described in the @xREST properties section of this topic.

The function parameters have one of two purposes:

If the function parameter corresponds to an argument in the uriTemplate, then the parameter is known as a query parameter or a path parameter. This usage is shown later in this topic, in the description of the @xREST properties. Those values are embedded in the URI. In particular, if the property is @GetREST, all of the arguments that are assigned to the function parameters are used to construct the URI.
If the function parameter does not correspond to an argument in the uriTemplate the argument is a representation processed by the service; for example, a record containing values used to create a database-table row.
Here are details:
- If the property is @PostREST or @PutREST for a given operation, the additional argument must be present, and the related parameter is called the representation parameter.
- The argument also might be required if the property is @DeleteREST. The need for such an argument depends on the service provider.

If the function has a parameter that is not identified in the uriTemplate property field (for @PostREST, @PutREST, or @DeleteREST), that parameter is a representation parameter. Either of the following cases is an error:

Specifying more than one representation parameter
Specifying a representation parameter when @GetREST is in use

@xREST properties used for EGL REST services

Each of the @xREST complex properties has these fields: uriTemplate, requestFormat, and responseFormat.

uriTemplate

A string, or template, that in most cases outlines a relative URI, which identifies the last qualifiers in the URI that are used to access the service. For background information, see “REST for the developer.”

The first URI qualifiers, the base URI, is specified in the deployment descriptor.

The value of the uriTemplate property has two aspects:

The value of the uriTemplate property can include a constant value. Those characters are present in or after every URI used to access the function. In the previous example, the value of uriTemplate includes a query variable, and the constant value is as follows:
```
/employee?code=
```
If the example is changed to include a path variable instead of the query string, the constant value is as follows:
```
/employee/
```

The value of the uriTemplate property can include path variables and query variables. The previous example includes a single query variable:
```
{employeeCode}
```
For the original example with a query string, here is a relative URI and value that are used to access the service:
```
/employee?code=02135
```
If the template includes a path variable instead of a query string, here is a relative URI:
```
/employee?code=02135
```

requestFormat

A value that indicates the format of the representation that is sent to the service:

XML, to indicate that the format is Extensible Markup Language
NONE, to indicate that the representation is a string, or a value that is compatible with a string, and is sent as is
JSON, to indicate that the format is JavaScript Object Notation

If the representation is a record, the following statements apply:

The default value of requestFormat is XML.
JSON is also valid.

responseFormat

A value that indicates the format of the representation that is returned to the requester:

XML, to indicate that the returned representation is in XML format
NONE, to indicate that the returned representation is a string
JSON, to indicate that the returned representation is in JSON format

If the return value in the Service part function is a string or a value that is compatible with a string, the default value of responseFormat is NONE, which is the only valid format. If the return value is a record, the default value of responseFormat is XML, and JSON is also valid.

Documenting EGL REST Services

When deploying EGL REST services, RBD generates an OpenAPI document that describes the service and how to invoke it. This document is placed in the WebContent\WEB-INF folder for Java deployments, or the genDirectory for CICS deployments.

Along with the @xREST properties, EGL provides several annotations for documenting REST services.

User can give the service a title.
User can specify a description for the EGL service, it’s functions and representation parameters.
User can specify a version number for the EGL service.

User can specify tags for each @xREST function, which will allows to group the service function in the OpenAPI document based on keywords.

record myEmployeeRecordPart type SQLRecord{description="Employee Record"}
	employeeCode STRING{description="Employee Code"};
	//other SQL columns;
end


Service EmployeeService {description="Access the Employee records", Title="Employee Service", version="1.0.0"}
   Function GetEmployeeDetail(employeeCode STRING IN) 
            returns(myEmployeeRecordPart)
      { description="retrieve an employee from the database",tags=["Employee","Record"],
      @GetRest{uriTemplate="/employee?code={employeeCode} }",
                requestFormat = JSON,
                responseFormat = JSON}};
	//service logic
	end
end

Compatibility

Platform	Issue
COBOL generation	Only JSON is supported for requestFormat and responseFormat EGL REST RPC is not supported. The representation parameter must be the same for all Service functions.

Platform

Issue

COBOL generation

Only JSON is supported for requestFormat and

responseFormat

EGL REST RPC is not supported.

The representation parameter must be the same for all

Service functions.