Overview

With the rising demand for proper and established standards with web-based applications SRP has been rather busy implementing Representational State Transfer (REST) APIs. We will be sharing our experiences and best practice approaches to this in upcoming articles. Since Semantic URLs are often considered an important element of implementing RESTful APIs we wanted to lead off with an article that explains how all versions of the OECGI can be hidden from the URL.

By way of brief review, most developers know that OpenInsight provides OECGIx.exe (henceforth OECGI3.exe) as a tool for enabling web traffic to execute OpenInsight procedures. This is accomplished by configuring the web server to run OECGI3.exe as a CGI script and then configuring OECGI3.exe to connect to a running OEngine server where the stored procedures are located. Web visitors are able to run the stored procedures simply by accessing a URL to execute the procedure. The procedure runs in OEngine and returns data such as an HTML web page, JSON data structure, XML document, or other HTTP document to the web browser making the request.

This article walks through the process of a technique called URL Rewriting to hide OECGI3.exe from the URL your visitors see. Instead of seeing a URL such as:

http://www.example.com/cgi-bin/oecgi3.exe/inet_trace

Visitors will see:

http://www.example.com/app/inet_trace

Note: Rules specifically tested for use with the SRP HTTP Framework are available here.

Why Use URL Rewriting

Beyond simply conforming to a RESTful style there are a number of additional reasons to use URL Rewriting and most web applications employ it for one or more of the reasons below:

• Cleaner experience – URLs become shorter and easier to read.
• Hide site technology – Visitors don’t need to see OECGI3.exe. To the tech-savvy visitor they might immediately know it’s probably an EXE program running on a Windows server.
• Compatibility – Sites will often use URL rewriting to prevent broken links. If you move to another version of OECGI3.exe or a different web technology the URL rewriting rules can be adjusted to prevent broken links.
• Redirection – Visitors can be seamlessly redirected to different pages or sites.

How URL Rewriting Works

The web server is configured to use the URL rewrite module and then programmed with short rules that instruct the module on how to ‘re-write’ URLs as they are requested. Let’s take the example URL:

http://www.example.com/app/inet_trace

When the web server receives a request for this URL it checks the rewrite module for any matching rules. In the example rule we’ll be walking through the rule to change app to cgi-bin/oecgi3.exe which in turn executes the full URL.

Under normal circumstances OECGI3.exe is unaware of the rewrite rule and thinks the request was for the complete URL. Let’s walk through setting up this simple URL rewrite rule.

Setting Up the Rule

This article focuses on setting up URL rewriting for IIS but also provides a sample configuration for Apache. The techniques should apply to any web server that supports URL rewriting.

IIS Prerequisites

• Windows Server 2008 running IIS 7.0 or later web server. The instructions below were written for Windows Server 2012 but the steps are almost identical on previous versions of Windows Server.
• The IIS URL Rewrite module should be installed from http://www.iis.net/downloads/microsoft/url-rewrite
• OECGI3.exe should already be installed and functioning. Refer to 103-960 OECGI3.EXE Quick Start Guide.pdf in your OpenInsight documents directory for more information on how to setup the web server.

Setting up the Rewrite Rule

1. Open the Internet Information Services (IIS) Manager window.
2. Browse to the root website directory. In our example this is in Default Web Site.
3. Locate and open the icon URL Rewrite icon as shown in the image below:
   
4. Click Add Rule(s)… in the Actions pane.
5. Under Inbound Rules choose Blank rule.
6. Supply a name such as CGI-BIN App Rewrite to indicate the purpose of the rule.
7. In the pattern prompt copy and paste the following:

    ^app/([_0-9a-z-]+)$

   Tip: This is a regular expression that instructs the url to match any url beginning with app/ followed by the characters _,0-9,a-z, or -. Your screen should match the following:
   

8. Finally under the action section for Rewrite URL copy and paste into the prompt:

    cgi-bin/oecgi3.exe/{R:0}

   Tip: This is what the rule will rewrite the matching portion of the URL to become and append any arguments in the URL onto the end:
   

9. Save the rule and skip to the section below Testing the Rewrite Rule.

Rewrite Rule for Apache

If you aren’t familiar with Apache it’s usually more intimidating to the novice and a step by step walk through of the configuration is beyond the scope of this article but the concepts of how rewriting functions is almost identical. If you are familiar with Apache and have already configured it to serve OECGI3.exe requests you can use the following .htaccess rule to do the same thing as the IIS rule from the previous section by copying these rules into the .htaccess file in your website home directory:

RewriteEngine on
RewriteBase /
RewriteRule ^app/?([_0-9a-zA-Z-]+)$ /cgi-bin/oecgi3.exe/$1

The rule’s regular expression is almost identical to the IIS version except it contains an additional match for capital letters. By default Apache is case sensitive and needs to specify that both lower case letters in the range of a-z and upper case letters in the range A-Z should be matched.

Testing the Rewrite Rule

The purpose of our rewrite rules was to shorten the URL and replace cgi-bin/oecgi3.exe with app to make the URLs more user friendly. To test the rule try opening the new shorter URL and verify the rewrite rules display the same content as the longer version.

If your setup is correct the URL http://www.example.com/app/inet_trace should display the following:

In our case, INET security was blocking inet_trace but we know it succeeded because the request did not generate an error and the dot was returned. This is the default behavior for new installations since OpenInsight 9.3.

The old url, http://www.example.com/cgi-bin/oecgi3.exe/inet_trace, is still active. Accessing the URL reveals the same result:

Checking the original URL without rewriting is a useful debugging step to verify if the cause of a broken link is due to the URL rewrite rule or the target of the rewrite rule.

Closing

This article only scratches the surface of what URL rewriting can do when used with OpenInsight and OECGI3.exe. We hope to document more examples in the future that will make it easier to transform traditional OECGI URLs into cleaner and more user-friendly addresses.

Revision: 02/07/2017 Added link to SRP HTTP Framework specific rewrite rules.