RESTful Aliases

Projects‎ > ‎

This project is designed to address the requirements (issue 142) for aliasing the RESTful interface. Leveraging an "alias" (to the RESTful end-point) enables the deployer to abstract the implemented resources / contexts and present a consistent URL that can be maintained should the actual RESTful end-point change.

Reference

Requirements

The current REST interface is quite flexible, but embeds details of the internals of the OpenPTK configuration in the URI.

A new feature to configure aliases to existing contexts through a new URI pattern would allow the exposed REST (URI) interface to be controlled by configuration. This page describes the design of the feature to create a new / customizable RESTful URL End-Point that can be mapped to an existing OpenPTK RESTful URL End-Point

Reference REST Interface

The HTTP Request has the following structure:

Existing Example:	http://localhost:8080/openptk-server/resources/contexts/User-JDBC-MySQL/subjects
Syntax:	{scheme}://{host}:{port}/{contextPath}/{servletPath}/{pathInfo}

Proposed Design:

This planned implementation of this is to be implemented as a servlet filter which simply looks for request patterns and redirects the requests to the actual resources in the existing REST interface. The design will use javax.servlet.RequestDispatcher in order to preserve the request and process the resonse, while ensuring that authentication and authorization are not negatively impacted. Using a servlet filter will also provide flexibility in the URI path that is used for the alias, without requiring configuration in the web.xml file.

With this approach, the new top level pattern would need to be selected. <alias> in the examples above was only used as a placeholder. The actual string itself could also be configurable, but we will need to select a default.

Since resources is currently used for the rest interface, it should be a different pattern. Should we consider not requiring a single pre-defined top level pattern for all aliases, and simply create a default one, with instructions for how to configure others? Would we ever want to support a direct alias mapping at the top level without a container? (if so this would require configuration of the web.xml file. The alias URL root name is the first "level" below where the OpenPTK Server is deployed. The default keyword is <TBD>. Some options :

services
objects
asset
capability
alias
route, router
redirect
detour
endpoint, end-point
top

The Aliases "end-point" can not be any of the reserved values. Two different Aliases can reference the same target URI.

This feature will allow multiple aliases to be created, that each point to a different real context, or two different Aliases can reference the same context.

Two examples of the the alias feature being used for existing URIs for 2 contexts:

Alias Example1

(All references below use an assumed context root of the openptk server of http://localhost:8080/openptk-server as a prefix.)

Variable	Value
Actual Destination	/resources/contexts/Employees-Embed-JDBC/subjects
alias-root	top
Exposed Alias	/top/employees
Full alias URL	http://localhost:8080/openptk-server/top/employees

In this example, <alias-root> is a single top top level pattern (/top) and /employees is an alias mapped to the context (Employees-Embed-JDBC).

Alias Example2

(All references below use an assumed context root of the openptk server of http://localhost:8080/openptk-server as a prefix.)

Variable	Value
Actual Destination	/resources/contexts/Customers-OpenDS-JNDI/subjects
alias-root	top
Exposed Alias	/top/v1/customers
Full alias URL	http://localhost:8080/openptk-server/top/v1/customers

In this example, <alias-root> is a top top level pattern (/top) and /v1/customers is an alias mapped to the context (Customers-OpenDS-JNDI).

The proposed name for the servlet filter is:

ResourceAliasFilter.java

The implementation of a servlet filter would require that this filter would fire first in the filter chain before authentication and authorization.

<filter>
        <filter-name>Alias</filter-name>
        <filter-class>org.openptk.servlet.filters.ResourceAliasFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>Alias</filter-name>
        <url-pattern>/alias/*</url-pattern>
    </filter-mapping>

Configuration:

The configuration in the openptk.xml file of the aliases would only require a simple entry in the configuration file to associate an alias with a specific context.

<Aliases>

<Properties>

<Property name="reserved" value="resources*,login,logout" />

</Properties>

<Alias endpoint="Users" reference="resources/contexts/User-JDBC-MySQL/subjects" mapper="scim-user-1.0-consumer" />

<Alias endpoint="v1/Users" reference="resources/contexts/User-JDBC-MySQL/subjects" mapper ="scim-user-1.0-consumer" />

<Alias endpoint="Users/v1" reference="resources/contexts/User-JDBC-MySQL/subjects" mapper ="scim-user-1.0-consumer" />

<Alias endpoint="Employees" reference="resources/contexts/Employee-JNDI-OpenDS/subjects" />

<Alias endpoint="Clients" reference="resources/clients" />

</Aliases>

The configuration will optionally include details for the attribute mapper to use for the request.

Triggering the alias and attribute mapping

Set HTTP Request Header Variables being considered:

Header Name
Description Example
X-OPENPTK-SERVLETPATH Partial URL for the servlet path
N/A
X-OPENPTK-PATHINFO Partial URL for the servlet path N/A
X-OPENPTK-ATTRMAP attribute mapper name to use
scim-user-1.0-consumer
X-OPENPTK-ALIAS-URL
Alias URL used by the client, needed for the rewriting of payload URLs
http://localhost:8080/openptk-server/alias/My/Users

Proposed Alias Flow

	Search this site