Introduction

A Gateway REST web service is a special type of REST service that is published on a Gateway Server. The purpose of Gateway REST web services is to enable applications running on a Remote Server to access local facilities on a Gateway Server in a secure manner. Gateway REST web services extend regular REST web services to add a security layer based on the trust relationship created between the Gateway Server and a Remote Server. Gateway REST web services can only be published on a Verj.io Gateway Server.

The Gateway Server makes the following security checks on receipt of a web service request:

· The Gateway Server licence feature must be enabled. This can be checked in the Server Administration Application

· The incoming request must contain the required authorization token (this is added automatically when a request is made from a Remote Server)

· The incoming IP address is checked against the Gateway Server IP Whitelist (optional)

1. The REST Web Service endpoint request (e.g /customer/getCustomer) is called from the Remote Server. The endpoint request should be invoked using the Gateway REST JavaScript API.

2. A Gateway authorization token is added to the request using the configured Gateway Server API Key.

3. The request is invoked on the Gateway Server containing the Authorization : Gateway <token> header

4. The Authorization Token is checked on the Gateway Server. If configured, the IP Whitelist is also checked at this point.

5. The REST service endpoint is invoked on the Gateway Server.

6. The HTTP response is returned to the remote server

A call to a Gateway REST web service endpoint from a Remote Server is made using the Gateway REST JavaScript API. This adds the required Authorization HTTP header e.g.

var response = gateway.rest.get("MyCorp_Gateway", "/customers/getCustomer");

Creating Gateway Server RESTful Web Services

A Gateway REST Web Service can be created by selecting New > REST Services > Gateway REST Service and edited by double clicking the service name.

The Gateway REST Web Service can be identified by the icon

A sample Gateway REST Web Service is provided in the VerjSamples project at location Modules/API.

See REStful Web Services for further documentation.

Gateway REST Request

A Gateway REST Web Service is published as a web service on a Gateway Server and is then invoked from a Remote Server using the following URL:

http://<domain-name>:<port>/<web-app>/gateway/<restful_service_name>/<endpoint-uri>

The Gateway REST Web Service documentation can be viewed by invoking:

http://<domain-name>:<port>/<web-app>/gateway/ebasePublishRest.eb?serviceName=<restful_service_name>

A Gateway REST Web Service can only be called using the Gateway REST JavaScript API.

Web Service HTTP Response Codes

The following table shows the possible HTTP error responses:

Http Response Code	Description	Example
200	Request is authorized and the endpoint has executed successfully	HTTP/1.1 200 OK { “firstname” : “fred”, “lastname” : “bloggs”, … }
400	An error processing the REST Web Service	HTTP/1.1 400 Bad Request Error executing RESTful Web Service
401	Missing HTTP header Authorization with the incoming request: Authorization: Gateway <token>	HTTP/1.1 401 Unauthorized WWW-Authenticate: Gateway realm=”MyCorp Gateway”>
403	Gateway Authentication Error – Token does not match the authorization token expected.	HTTP/1.1 403 Forbidden Authentication Error : customer
404	REST Web Service is not found.	HTTP/1.1 404 Not found RESTful Web Service name is not found - customer
500	Any unhandled errors (server error) - the detail error message is returned in the response body.	HTTP/1.1 500 Internal Error Invalid Gateway Token

Use the REST JavaScript API to specify the HTTP Response code in the endpoint script.

IP Whitelist

The IP Whitelist is configured using the Server Administration Application. This can be used as an additional security check to verify that an incoming request is from an authorized server. Use of an IP Whitelist for added security is highly recommended.

Gateway REST JavaScript API

The Gateway REST Web Service functionality is provided by the GatewayRESTServices JavaScript API and can be accessed using the JavaScript variable gateway.rest.

The gateway.rest JavaScript API is an extension to the RestServices API and provides all the same methods get(), put(), post(), delete() etc, except that each of the methods must include the following parameters:

The Remote Gateway Server name as the first parameter that configured using the Server Administration Application
The endpoint URL which will have the format:

<gateway-restful-web-service-name>/<endpoint-name>

It not possible to specify the HTTP Authentication method when using the gateway.rest API, this is because authorization using a gateway token is implied.

For full details see Gateway Programming API.

Example:

var response = gateway.rest.get("MyCorp_Gateway", "/customers/getCustomer");

if (response.isSuccess())

    var results = JSON.parse(response.getBody());

..