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/
- 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.
|