Gateway REST Web Services

Documentation home

 

Introduction. 1

Creating Gateway RESTful Web Services 3

Gateway REST Request 3

Web Service HTTP Response Codes 3

IP Whitelist 4

Gateway REST JavaScript API 4

Example. 4

 

 

 

See also: Verj.io Gateway, Publishing RESTful Web Services, Gateway REST JavaScript API

 

Introduction

A Gateway REST web service is a special type of REST service that is published on a Verj.io Gateway. The purpose of Gateway REST web services is to enable applications running on remote Verj.io On-Premises environment or Verj.io Service Plan to access local facilities on a Gateway 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 Verj.io Gateway and remote Verj.io On-Premises environments and Verj.io Service Plans. Gateway REST web services can only be published on a Verj.io Gateway.

 

The Verj.io Gateway makes the following security checks on receipt of a web service request:

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

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

 

 

 

1.      The REST Web Service endpoint request (e.g /customer/getCustomer) is called from the remote Verj.io Application. 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 containing the Authorization : Gateway <token> header

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

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

6.      The HTTP response is returned to the remote server

 

 

A call to a Gateway REST web service endpoint from a Remote Verj.io Application 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 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 Verj.io Gateway and is then invoked from a remote Verj.io Application 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:

 

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

Example

 

var response = gateway.rest.get("MyCorp_Gateway", "/customers/getCustomer");
if (response.isSuccess())
{
    var results = JSON.parse(response.getBody());
    ..
}