How to configure a URL Alias for a REST Resource in webMethods Integration Server

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:


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


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:

Creating a URL Alias in webMethods Integration Server

  • 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:

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

Calling a REST Resource via a URL Alias in webMethods Integration Server

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:


3 thoughts on “How to configure a URL Alias for a REST Resource in webMethods Integration Server”

  1. Hello Stefan Macke
    I would like to delete the “/gateway” in the URL: https: // apigatewayhost / gateway / myApiName

    I want to hide the URL of my API:

    http: // /gateway/myApiName
    http: // /myApiName

    I tried to follow the same procedure as you, creating an alias and changing the [b]watt.server.url.alias.partialMatching[/b] parameter to true, but the call is still done via the old URL.

    Do you have an idea about that?

    Thanks in advance

Leave a Comment

To create code blocks or other preformatted text, indent by four spaces:

    This will be displayed in a monospaced font. The first four 
    spaces will be stripped off, but all other whitespace
    will be preserved.
    Markdown is turned off in code blocks:
     [This is not a link](

To create not a block, but an inline code span, use backticks:

Here is some inline `code`.

For more help see