You define an EGL Interface part in a file that is made
available to the requester of that service. The Interface part can
be in the same EGL package or can be imported from a separate package.
An EGL
Interface part includes one or more function prototypes,
which are descriptions of how to write code to access a given service
operation. A function prototype includes the operation name, parameters
(if any), and a return type (if any). The prototype does not include
the logic of the operation, which is available in the service only.
The Interface part of an EGL REST-RPC service is simpler than an
Interface part for a third-party REST service.
Interface part for accessing an EGL REST-RPC service
This
example shows an Interface part for accessing an EGL REST-RPC service.
The example includes a single function prototype:
Interface EmployeeService
Function GetEmployeeDetail(employeeCode STRING IN,
employeeSalary FLOAT OUT,
employeeStatus STRING INOUT)
returns(myEmployeeRecordPart);
end
You can specify various EGL data types and can
use the modifiers IN, OUT, and INOUT.
To create the Interface
part:
- In the Project Explorer view, right-click the EGL file that defines
the service
- Click .
- In the New EGL Interface part window, specify the appropriate
details, and click Finish.
Interface part for accessing a third-party REST service
This
example shows Interface part for accessing a third-party REST service:
Interface WeatherForecast
Function GetWeatherByZipCode(zipcode string in) returns(myRecordPart)
{@GetRest{uriTemplate="/GetWeatherByZipCode?zipCode={zipcode}",
requestFormat = JSON,
responseFormat = JSON}};
end
If the purpose of the Interface part is to describe
the operations that are available in a third-party REST service (not
an EGL REST-RPC service), you must specify a complex property for
each function prototype. 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.
In the service-invocation
statement that is used to access a third-party REST service, the argument
that is passed to a given function parameter has one of two purposes:
- Usually, the argument provides a value that the requester includes
in the URI. This usage is shown later in this topic, in the description
of the @xREST properties. Those values are not passed to the service
logic; they are values that 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.
- In the case of one argument (at most), the argument is a representation
that is processed by the service; for example, a record that contains
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 prototype 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
For restrictions on the arguments sent to a service, see
“Restrictions in the prototypes used for service access.”
You
do not need to create an Interface part. Instead, you can use IRest,
which is an Interface part that is provided for you and that can be
the basis of a variable that is used to access a third-party REST
service. For more information about that Interface part, see “Using
a provided Interface for a third-party REST service.”
@xREST properties used for third-party 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,
are specified in one of three ways:
- When you declare a variable that is based on the Interface part,
you can set the base URI. In this case, the base URI is set at development
time, and no change is possible at configuration time or run time.
This usage is simple and fast, but inflexible.
- Alternatively, when you declare a variable based on the Interface
part, you can identify an entry in a deployment descriptor. In this
case, an initial value for the base URI is in the deployment descriptor,
and at configuration time, a code installer can change that value.
- You can run the serviceLib.setServiceLocation function
to change the value of the base URI at run time, regardless of how
you specify an initial value.
If you do not set the base URI, the value of the uriTemplate property
field includes the complete URI. In most cases, 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 that is used to access the function. In the previous example,
the value of uriTemplate includes a query
variable, and the constant value is as follows:
/GetWeatherByZip?zipcode=
If
the example is changed to include a path variable instead of the query
string, the constant value is as follows:
/GetWeatherByZip/
- The value of the uriTemplate property
can include path variables and query variables. The previous example
includes a single query variable:
{zipcode}
For
the original example with a query string, here is a relative URI and
value that are used to access the service:
/GetWeatherByZip?zipcode=02135
If
the template includes a path variable instead of a query string, here
is a relative URI:
/GetWeatherByZip/02135
The
EGL runtime code automatically completes a URI encoding on each substitution
value that is specified in a service invocation statement, with one
exception.
For example, if your service-invocation statement
indicates that the value for a given substitution variable is "Jeff
Smith", the EGL runtime code converts the string to "Jeff%20Smith"
so that the URI is valid. However, if the value of a substitution
value begins with http, the EGL runtime code does no URI encoding
because the service-invocation statement is specifying an argument
that provides a complete URI. If you are responsible for URI encoding,
review the documentation on the serviceLib.convertToURLEncoded system
function.
The default value of the uriTemplate field
is an empty string so that, by default, you can specify the complete
URI by setting the base URI.
- 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
- FORM, to indicate that the format is form data, which is a record
composed of argument-value pairs. In the following example of the
content sent to the service, each pair is separated from the next
by an ampersand (&):
division=Consumer&dept=Sales
For
a given field in the Record part that is the basis of form data, you
can specify the
FormName property. You can
use that property to work with an argument name that is an EGL reserved
word or is not valid in EGL. Here is an example use of the
FormName property:
record anyRecord
continue boolean {FormName="continue-content"};
end
The runtime code uses the value of the
FormName property
as the name of the argument transmitted to the service. Here is a
representation that might be sent to the service:
continue-content=yes
The
default value of the FormName property is
the name of the record field. In this example, the default is continue.
You
cannot override the value of the FormName property
when you declare a record that is based on the Record part.
If the representation is a record, the following statements
apply:
- The default value of requestFormat is XML.
- JSON is also valid.
- FORM is valid only if every field in the record is of type
STRING or is of a type that is assignment-compatible with STRING. FORM is
not valid if the record references another record.
- 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 Interface part function prototype
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.
You can specify an
@xREST property
without assigning values to the property fields:
Interface IEmployeeService
Function GetEmployeeDetail() returns(myRecordPart)
{@GetRest{}};
end
The lack of property fields indicates these
behaviors:
- You must provide the complete REST service URI, such as http://www.ibm.com/myservice,
without providing detail in the Interface part. For information about
the three choices for specifying the base URI, see the description
of uriTemplate in this topic.
- If the representation parameter (or, for the @GetREST property,
the return value) is a string, the EGL runtime code does no conversion.
You must handle the conversion and can use any of the following functions
for that purpose:
- serviceLib.convertFromJSON
- serviceLib.convertToJSON
- XMLLib.convertFromXML
- XMLLib.convertToXML
- If the representation parameter is a record, the EGL runtime code
converts the related argument to Extensible Markup Language (XML)
format.
- For the @GetREST property, if the return
value is a record, the EGL runtime code converts that record from
XML format.
.