Using REST Pass-through Services and Operations

This section adds a REST pass-through service and a REST pass-through operation. The service listens on the Web port and sends the HTTP REST message to the pass-through operation. The pass-through operation sends the HTTP REST message to an external server, api.openweathermap.org, that returns current weather information.

Select or create a namespace and production. In order to use the Web port, you must define a web application in the namespace and a role. See Configuring an InterSystems IRIS System for step-by-step instructions to create a namespace, role, and web application. For this walkthrough, name the web application /restpassthrough (web application name should be lower case) and set the web application Dispatch Class to EnsLib.REST.GenericServiceOpens in a new tab.

On the production configuration page, click the plus sign for adding new operations.
1. Specify the operation class: EnsLib.REST.GenericOperationOpens in a new tab
2. Name the operation, such as WeatherRESTPassthroughOp.
3. Don't enable it yet.
4. Select OK.
Select the Pass-through operation that you created and click the Settings tab.
1. If you are using the external service registry, set the External Registry ID to identify the registry entry that sets the HTTP Server,HTTP Port, and URL settings and skip to Step 3. Otherwise specify these settings directly as follows:
2. Enter the HTTP Server: api.openweathermap.org
3. Set the URL field to: |
4. Leave the other fields at their default values.
5. Check the Enabled check box.
6. Select Apply.
Click the plus sign for adding new services.
1. Specify the service class: EnsLib.REST.GenericServiceOpens in a new tab
2. Name the service, such as WeatherRESTPassthroughServ.
3. Don't enable it yet.
4. Select OK.
Select the Pass-through service that you created and click the Settings tab.
1. Ensure that the Port number is blank.
2. In the TargetConfigName field, choose the pass-through operation that you added in the previous step.
3. In Connection Settings, check the Enable Standard Requests check box.
4. In Additional Settings, set Pool Size to 0. This suppresses the pass-through service from listening on the special port. If do not set the pool size to 0, you must specify a port number.
5. Check the Enabled check box.
6. Select Apply.
Start the production.
Enter the URL for the pass-through service using the Web port. The URL has the following form:
- https://<baseURL>/ — the <baseURL> for your IRIS instance.
- web-application-name/ that you specified, for example restpassthrough/. See Configuring a Web Application for a Pass-through Business Service.
- passthrough-service-name/ — for example, WeatherRESTPassthroughServ/
- URL required by the external service, such as data/2.5/weather?q=London&appid=asd9g87w42MyAPIKey. You need to sign-up for an OpenWeather account to obtain an API key.
For example, enter the following URL in a web browser, including the API key that you obtained from OpenWeather:
http://<baseURL>/restpassthrough/WeatherRESTPassthroughServ/data/2.5/weather?q=London&appid=asd9g87werMyAPIKey
Note that all alphabetic characters in the web application name must be in lower case and the pass-through service name must match the case of the configuration item name.

If all is working, the call returns a JSON message with the current weather in London. For example, it can return the following JSON message:

{
"coord":{"lon":-0.13,"lat":51.51},
"sys":{"message":0.0441,"country":"GB","sunrise":1399609017,"sunset":1399664214},
"weather":[{"id":802,"main":"Clouds","description":"scattered clouds","icon":"03n"}],
"base":"cmc stations",
"main":{"temp":285.32,"pressure":1008,"temp_min":284.15,"temp_max":286.48,"humidity":91},
"wind":{"speed":5.14,"gust":6.17,"deg":284},
"rain":{"3h":0},
"clouds":{"all":32},
"dt":1399600508,
"id":2643743,
"name":"London",
"cod":200
}

Pass-through Background Information

Notice how the URL is transformed between your call to the pass-through service and the call to the external server. The URL sent to the pass-through service has the following form, using the <baseURL> for your instance:

http://<baseURL>/Restpassthrough/WeatherRESTPassthroughServ/data/2.5/weather?q=London

and the URL sent to the external server is:

http://api.openweathermap.org/data/2.5/weather?q=London

The last parts of the URL starting with data are identical. The HTTP Server field sets the server in the outgoing call. The | in the URL field instructs the operation to strip the web application name and configuration name from the incoming URL and then include the remainder in the outgoing URL.

Note:

The EnsLib.REST.GenericServiceOpens in a new tab class does not provide any additional functionality over the EnsLib.HTTP.GenericServiceOpens in a new tab class. Although you could use the EnsLib.HTTP.GenericServiceOpens in a new tab class to pass-through a REST call, you should use the appropriate subclass.

Pass-through Troubleshooting

There are a few troubleshooting steps you can take if you don't get the expected results.

Enter the openweathermap URL directly in the web browser without using InterSystems IRIS. Enter the following URL in the web browser:
```
http://api.openweathermap.org/data/2.5/weather?q=London,uk
```
This ensures that the weather server is working correctly.
Examine the production message tracing for the production. A successful message trace looks like the following:
The trace may help you identify where the error is.
Run a TCP trace utility. Specify a local port to listen on, the server api.openweathermap.org, and port 80. In the pass-through operation settings, set the following properties:
- HTTP Server: localhost
- HTTP Port: port that TCP trace is listening on
Then Select Apply and enter the pass-through service URL in a web browser, using the <baseURL> for your instance:
http://<baseURL>/Restpassthrough/WeatherRESTPassthroughServ/data/2.5/weather?q=Boston,ma
The TCP trace should show the HTTP request being sent out by the pass-through operation and the server's response.

Using SOAP Pass-through Services and Operations