Declaring a variable to access a REST service

To provide additional details about how to access the REST service, you declare a variable in the requester. That variable is based on the Interface part.

For example, here is a declaration that is based on an Interface part named WeatherForecast: 
myService WeatherForcast {@RESTBinding {baseURI="http://www.ibm.com/gateway"}};
In that declaration, you can specify either of two properties, each of which gives you a way to specify the following details:
  • The initial value of the base URI, which is a set of high-level qualifiers for the service location.
  • The session cookie ID, which is a string that identifies the session cookie that is provided to the EGL Rich UI proxy from a service. The service logic in this case is stateful, which means that the user and logic can participate in a multistep conversation. This setting is meaningful if an EGL external type makes an IBM® i program or service program available as an EGL REST-RPC service and if the requester is a Rich UI application. For background information, see "Accessing IBM® i programs as web services."

    When you use stateful REST services, the connection and all the associated IBM® i resources are retained until the session on the service side is invalidated. The service-side session is invalidated when the requesting code invokes the serviceLib.endStatefulServiceSession() system function or when the application server invalidates the session, typically because of a timeout.

The two properties are @RESTBinding and @BindService. You can use the @RESTBinding property to specify the base URI and session-cookie ID directly in your code. This option is simple but inflexible. You can use the @BindService property to specify those details in a deployment descriptor, as allows for changes at configuration time.

The two properties are mutually exclusive:
@RESTBinding
Use this property to specify, in your code, the base URI in the code, the session cookie ID, or both. @RESTBinding includes the following fields:
baseURI
A string that identifies the first qualifiers in the URI that is being used to access the service. The default value of baseURI is an empty string.
sessionCookieID
The name of a session cookie. The default value is JSESSIONID, which is always the session ID when your application runs on Apache Tomcat.
The setting of the sessionCookieID field is meaningful only in the following cases:
  • The service is an EGL external type that makes an IBM® i called program or service program available as an EGL REST-RPC service; and
  • The service logic is stateful, which means that the requester and service can participate in a multistep conversation

The value of this field overrides the setting of the defaultSessionCookieID build descriptor option.

@BindService
Use this property to use a deployment-descriptor entry to identify the base URI, the cookie-session-ID, or both. The property has one field:
bindingKey
Identifies the deployment-descriptor entry that includes the two details.
You can specify the @BindService property without specifying the bindingKey field. In that case, the property identifies the deployment-descriptor entry that has the same name as the Interface part. Here is an example of that usage, which refers to the deployment-descriptor entry named WeatherForecast:
MyService WeatherForecast {@BindService{}}

For details about setting up the EGL deployment descriptor, see Adding a REST binding to the deployment descriptor.