Interoperable Web Systems Architecture (IWSA)

Jeffrey A. Young
2006-07-22

Overview

The Interoperable Web Systems Architecture (IWSA) is a conceptual model for implementing Web Systems.

An IWSA System should be understood to be a set of abstract IWSA Resources that are recognized by the System and against which clients can invoke Services. IWSA Resources and Services can only be understood concretely in relation to one another. Considered properly, this model should be able to support any conceivable web service.

This model defines IWSA Resource URI patterns, interoperable Service-invocation URL patterns, and a minimal set of general-purpose Services. Systems are free to extend this architecture by appending additional information to the URL/URI patterns and defining new Services.

An OpenURL Community Profile representing this IWSA model is pending.

IWSA Definitions

The following terms, when italicized in this standard, have the meanings indicated here:

Term	Definition
BaseURL	This URL identifies and locates an IWSA installation on the web.
ComponentResourceLabel	This Label is used to identify component IWSA Resources within a System. Note, however, that query strings could be used instead of, or in conjunction with, ComponentResourceLabels for this purpose.
GlobalSystemLabel	An optional globally-unique Label for a System that can be used to facilitate interoperability across BaseURLs. If used, this label MUST be registered in the IWSA System Registry. Note! the Labels "webservices" and "localhost" are reserved for the purposes described below.
Identifier (ID)	This term is ambiguous, so it is generally avoided in this standard in favor of the terms Label and URI.
IWSA Resource	A Resource is an abstract entity known to, or discoverable by, an IWSA System. Resources can be accessed by performing a Service against it to produce a concrete representation.
Label	Labels are Unicode strings that identify IWSA Resources. Labels are used in the construction of URI and URL patterns described below. Note! ComponentResourceLabels are the only Labels that are allowed to use the '/' separator character. Without this restriction, it might be impossible to parse the URL patterns described below unambiguously.
LocalSystemLabel	A locally-unique Label for a System. LocalSystemLabels are differentiated from GlobalSystemLabels to give IWSA installations some leeway in the makeup of their URL patterns. Note! the label "webservices" and "localhost" are reserved for the purposes described below.
Service	A Service is a modular function that can be applied to an abstract IWSA Resource to generate a concrete result.
ServiceLabel	A local Label for a Service. Each Service also has a globally-unique URI representation that can be used to identify Services across Systems. The use of local Labels gives IWSA installations some leeway in the makeup of their URL patterns.
System	System is roughly equivalent to a Servlet webapp. Multiple systems can exist on a server in the same sense and for the same reasons that multiple webapps can exist on server. For purposes of this architecture, however, the implementation mechanisms used to differentiate systems are less important than the general concept.
URI	Info URIs (viz. info:iwsa/) are used to identify all IWSA Resources.

"info" URIs for IWSA Resources

"info" URIs can be used to identify IWSA Resources in their abstract form. IWSA implementations can use the Label "localhost" in place of {GlobalSystemLabel} to refer to themselves internally.

Resource	URI Pattern	Analysis
System	info:iwsa/{GlobalSystemLabel}	This form of the URI identifies a globally-recognized System.
System-defined	info:iwsa/{GlobalSystemLabel}/{ComponentResourceLabel}	This form of the URI indicates that individual Systems can extend the preceeding URI as they see fit to represent the individual IWSA Resources that they recognize.

Service URL Patterns

These general-purpose URL patterns are defined by the standard to facilitate ease of use and network interoperability. The ComponentResourceLabel, including a query string, can vary according to the needs of the Service being invoked. These patterns are optional. IWSA installations are free to ignore them in favor their own custom Service URL patterns. The penalty for this is a loss of interoperability from general purpose clients that want to vary the BaseURL while assuming these patterns.

Note that LocalSystemLabels are used in place of GlobalSystemLabels in order to give the System more leeway in the presentation of their URLs.

Web Services Pattern

This is the general-purpose pattern that can be used to invoke a Service against an IWSA Resource. This pattern is differentated from the Default Service Pattern by the presence of the reserved Label "webservices" in the position where the Default Pattern would expect to find a LocalSystemLabel.

URL Pattern	Analysis
{BaseURL}/webservices/{LocalSystemLabel}/{ServiceLabel}	Performs a Service against the specified System.
{BaseURL}/webservices/{LocalSystemLabel}/{ServiceLabel}/{ComponentResourceLabel}	Performs a Service against an IWSA Resource represented by the ComponentResourceLabel.

Example: http://worldcat.org/webservices/registry/ui/institutions/1234

Default Service Pattern

This is a shorthand for the Web Services Pattern that assumes a default ServiceLabel defined by the System.

URL Pattern	Analysis
{BaseURL}/{LocalSystemLabel}	Performs a default Service against the specified System.
{BaseURL}/{LocalSystemLabel}/{ComponentResourceLabel}	Performs a default Service against an IWSA Resource represented by the ComponentResourceLabel.

Example: http://worldcat.org/registry/institutions/1234

Custom Service URLs

In general the webservices pattern described above can and should be used for any miscellaneous ServiceLabel and a proliferation of alternative URL patterns is generally discouraged.

The main justification for wanting to create a custom service URL pattern is to provide backward compatibility with legacy URL patterns. Even in this case, though, the System administrator should consider supporting the patterns listed above for the sake of interoperability with generic clients.

Generic Services

The following Services are identified as being generally applicable to any conceivable IWSA System.

System-Level ServiceLabels

Note! If the ServiceLabel is missing from this pattern, the System should perform an HTTP redirect to the default ServiceLabel defined for this System. If the LocalSystemLabel is also missing, the System should perform an HTTP redirect to the default LocalSystemLabel.

Pattern: {BaseURL}/webservices/{LocalSystemLabel}/{ServiceLabel}
Example: http://worldcat.org/webservices/registry/listServices

Suggested ServiceLabel	Service URI	Description
listServices	info:iwsa/iwsaRegistry/services/listServices	Return a list of Service descriptions available for this System (mainly the list shown here).
default	info:iwsa/iwsaRegistry/services/default	Perform the default Service against info:iwsa/localhost.
ui	info:iwsa/iwsaRegistry/services/ui	Get a UI view of info:iwsa/localhost.
getGlobalSystemLabel	info:iwsa/iwsaRegistry/services/getGlobalSystemLabel	Returns the GlobalSystemLabel ("text/plain") that corresponds to the LocalSystemLabel, if one is registered in the IWSA System Registry.

Component Resource-Level ServiceLabels

Individual Component Resource-Level Services should be defined according to the needs of the System. Regardless of the System, however, the URL pattern described here should apply.

Pattern: {BaseURL}/webservices/{LocalSystemLabel}/{ServiceLabel}/{ComponentResourceLabel}
Example: http://worldcat.org/webservices/registry/edit/institutions/123

Note! ServiceLabels MUST appear after the LocalSystemLabel and before the ComponentResourceLabel. This rule exists to avoid ambiguity in cases where ComponentResourceLabels contain one or more '/' characters. In contrast to the example above, imagine if the "edit" ServiceLabels appeared after the "institutions/123" ComponentResourceLabel rather than before:

{baseURL}/webservices/{LocalSystemLabel}/institutions/123/edit

If a user then hacked the URL by chopping off the trailing "/edit", the System would incorrectly assume "123" was a ServiceLabel rather than part of the ComponentResourceLabel. The approved pattern avoids this ambiguity.

Custom Services

An IWSA administrator can add custom services as needed to apply to their peculiar IWSA Resources.