After I created my first REST Resource in webMethods Integration Server, I immediately saw potential for improvement regarding the URL under which it was made accessible:

http://localhost:5555/rest/ExamplePackage/Resources/Session

The default URL always starts with rest followed by the fully qualified name of the REST Resource. What bugs me is the latter: the path exposes the internal package structure to the outside. And if – for whatever reason – we decide to change this structure later, all clients need to be changed accordingly. And due to REST’s loose coupling you may not be aware of all consumers of your service and only find out late in the process that you missed to update a caller.

So, what we want is a logical URL instead of a physical one that represents our package structure, e.g.:

http://localhost:5555/User/Session

This logical URL should never change due to an internal restructuring.

URL Aliases

Integration Server provides an easy way of creating such logical URLs: URL Aliases.

You can find the dialog for creating URL Aliases in Integration Server’s web interface under Settings -> URL Aliases:

• Alias
  This is the logical URL you want to define for your REST resource, e.g. User/Session.
• URL Path
  The Alias above gets expanded to this fully qualified path, e.g. rest/ExamplePackage/Resources/Session.
• Package
  The Alias will be saved to this package. It resides in an XML file called config/urlalias.cnf in the package’s folder in the file system and can be versioned along with the rest of the package’s contents.

Now I can call the REST Resource via the URL Alias:

curl^
      -u Administrator:manage^
      -X POST^
      -H "Accept: application/json"^
      -H "Content-Type: application/json"^
      -d "{\"Username\":\"Stefan\",\"Password\":\"secr23et\"}"^
      http://localhost:5555/User/Session

Partial Matching

As stated in the REST Developer’s Guide, you may need to activate Partial Matching for your URL Aliases to work. See Integration Server Administrator’s Guide for details.

All you need to do is add this Extended Setting and restart IS:

watt.server.url.alias.partialMatching=true