Configurable reverse proxy server to access external APIs from within Oracle Application Express, without needing to deal with common SSL certificate issues. IMPORTANT: Recommended for development use only!
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
config
docker-scripts
.gitignore
Dockerfile
LICENSE
README.md
app.js
docker-dev.md
package.json

README.md

Introduction

Suez is a simple Nodejs application for proxying to web resources such as RESTful web services. While accessing web resources over a secure transport layer is strongly encouraged, certain software and budget limitations may prohibit us from adopting security best practices.

Suez was written specifically as a workaround for Oracle Application Express developers who use and deploy applications to an Oracle Database Express Edition database. The database software is provided free by Oracle and hence, lacks continued software support/upgrades and tools for managing the Oracle Wallet and SSL certificates.

To circumvent this limitation, Suez acts as a bridge between secured web services and an APEX application.

Software Requirements

  • Node.js(r) - should run on both LTS and non-LTS versions

Installation and Deployment

Note see Docker Support if you want to use SUEZ's docker container instead.

The following instructions are based on a CentOS 7 environment as recommended in the OXAR project. Please adapt based on the operating system available to you.

  1. In the destination directory, e.g. /opt, clone the project.
$ git clone https://github.com/fuzziebrain/suez.git
  1. Make a copy of the sample configuration file and adapt as needed. Please see the configuration section for details.

  2. Run the application:

$ node /opt/suez/app.js

Deployment

Using PM2 to run Suez as a service is encouraged. Please see the quick start guide for more information.

Configuration

A sample configuration file is provided and shown below:

{
  "service": {
    "port": 3000
  },
  "apiTargets": [
    {
      "name": "typicode",
      "proxyTarget": "https://jsonplaceholder.typicode.com/"
    },
    {
      "name": "acmeapi",
      "proxyTarget": "https://api.acme.com/"
    }
  ]
}

In the example, Suez is configured to listen to port 3000 and will provide access to two different API targets: typicode and acmeapi.

To configure Suez, make a copy of this file, change the service port number, if necessary, and then add apiTargets as required. Save this file and name it settings.json.

Usage

The following example is based on the sample settings file provided. Note: https://jsonplaceholder.typicode.com/ is a demo site for developers to test their RESTful API calls.

Suppose the developer would like to access the users via typicode's API. The URI provided by the vendor is https://jsonplaceholder.typicode.com/users. The corresponding PL/SQL code use to interact with service would look something like this:

l_response := apex_web_service.make_rest_request(
  p_url => 'http://typicode.localhost:3000/users'
  , p_http_method => 'GET'
);

Known Issues

  1. If the subdomain of localhost is unresolvable, add it to the hosts file, for example:
# For Linux: /etc/hosts
# For Windows: %SystemRoot%\System32\drivers\etc\hosts
127.0.0.1   localhost contosoapi.localhost acmeapi.localhost

Docker Support

If you don't want to install anything you can use the SUEZ docker image.

Get Docker image

docker pull fuzziebrain/suez

Run Container

# Note my settings.json is stored in ~/docker/suez
docker run -it -d \
  --name=suez \
  -v ~/docker/suez:/app/suez/config \
  -p 8888:3000 \
  fuzziebrain/suez:latest

# Stopping immediately using the -t 1
docker stop -t 1 suez

docker start suez

Container Parameters

Parameter Description
-e WATCH=true Optional: setting this to WATCH=true will restart the node service each time settings.json is changed. This is recommended for active development environments
--name Optional: Name to label container
-v <local dir>:/app/suez/config Location where settings.json is stored
-p 8888:3000 Suez uses port 3000 internally and this must be used, map it accordingly to your system. In this case port 8888 will be mapped to the container's port 3000.