Skip to main content

Introduction to Web Services and Web Clients in InterSystems IRIS

InterSystems IRIS® supports SOAP 1.1 and 1.2 (Simple Object Access Protocol). This support is easy to use, efficient, and fully compatible with the SOAP specification. This support is built into InterSystems IRIS and is available on every platform supported by InterSystems IRIS.

Introduction to InterSystems IRIS Web Services

This section introduces InterSystems IRIS web services.

Creating InterSystems IRIS Web Services

In InterSystems IRIS, you can create a web service in any of the following ways:

  • By converting an existing class to a web service with a few small changes. You also need to modify any object classes used as arguments so that they extend %XML.AdaptorOpens in a new tab and can be packaged in SOAP messages.

  • By creating a new web service class from scratch.

  • By using the InterSystems IRIS SOAP Wizard to read an existing WSDL document and generate a web service class and all supporting type classes.

    This technique (WSDL-first development) applies if the WSDL has already been designed and it is now necessary to create a web service that complies with it.

InterSystems IRIS Web Service as Part of a Web Application

An InterSystems IRIS web service must run within a web application that you configure within the Management Portal. Specifically, before you can use a web service class, you must define a web application that uses the namespace that contains the class.

For details on defining and configuring this web application, see Defining Applications in the Authorization Guide.

The WSDL

When the class compiler compiles a web service, it generates a WSDL for the service and publishes that via your configured web server, for your convenience. This WSDL complies with the Basic Profile 1.0 established by the WS-I (Web Services Interoperability Organization).Opens in a new tab In InterSystems IRIS, the WSDL document is served dynamically at a specific URL, and it automatically reflects any changes you make to the interface of your web service class (apart from header elements added at runtime). In most cases, you can use this document to generate web clients that interoperate with the web service.

For details and important notes, see Viewing the WSDL.

Web Service Architecture

To understand how an InterSystems IRIS web service works by default, it is useful to follow the events that occur when the web service receives a message it can understand: an HTTP request that includes a SOAP message.

First consider the contents of this HTTP request, which is directed to a specific URL:

  • HTTP headers that indicate the HTTP version, character set, and other such information.

    The HTTP headers must include the SOAP action, which is a URI that indicates the intent of the SOAP HTTP request.

    For SOAP 1.1, the SOAP action is included as the SOAPAction HTTP header. For SOAP 1.2, it is included within the Content-Type HTTP header.

    The SOAP action is generally used to route the inbound SOAP message. For example, a firewall could use this header to appropriately filter SOAP request messages in HTTP. SOAP places no restrictions on the format or specificity of the URI or that it is resolvable.

  • A request line, which includes a HTTP method such as GET, POST, or HEAD. This line indicates the action to take.

  • The message body, which in this case is a SOAP message that contains a method call. More specifically, this SOAP message indicates the name of the method to invoke and values to use for its arguments. The message can also include a SOAP header.

Now let us examine what occurs when this request is sent:

  1. The request is received by a third-party web server.

  2. Because the request is directed to a URL that ends with .cls, the web server forwards the request to the Web Gateway.

  3. The Web Gateway examines the URL. It interprets part of this URL as the logical name of a web application. The Gateway forwards the request to the appropriate physical location (the page for the web service), within that web application.

  4. When the web service page receives the request, it invokes its OnPage() method.

  5. The web service checks whether the request includes an InterSystems IRIS SOAP session header and if so, resumes the appropriate SOAP session or starts a new one.

    Note:

    This step refers to SOAP sessions as supported by InterSystems IRIS SOAP support. The SOAP specification does not define a standard for sessions. However, InterSystems IRIS SOAP support provides a proprietary InterSystems IRIS SOAP session header that you can use to maintain a session between a web client and a web service, as described here.

  6. The web service unpacks the message, validates it, and converts all input parameters to their appropriate InterSystems IRIS representation. For each complex type, the conversion creates an object instance that represents the complex type and uses that object as input for the web method.

    The SOAP action from the HTTP header is used here to determine the method and hence the request object.

    When the web service unpacks the message, it creates a new request object and imports the SOAP message into that object. In this process, the web service uses a generated class (a web method handler class) that was created when you compiled the web service.

  7. The web service executes the requested InterSystems IRIS method, packages up the reply, and constructs a SOAP response, including a SOAP header if appropriate.

  8. The web service writes the SOAP response (an XML document) to the current output device.

The following figure shows the external parts of this flow:

http request routed to an InterSystems IRIS CSP page through a web server that has a web gateway

Introduction to InterSystems IRIS Web Clients

This section introduces InterSystems IRIS web clients.

Creating InterSystems IRIS Web Clients

In InterSystems IRIS, you create a web client by using the InterSystems IRIS SOAP Wizard to read an existing WSDL document. The wizard generates a web client class and all supporting type classes.

The generated web client interface includes a client class that contains a proxy method for each method defined by the web service. Each proxy uses the same signature used by the corresponding web service method. The interface also includes classes to define any XML types needed as input or output for the methods.

a proxy client class where each method corresponds to a method in the web service

Typically you do not customize the generated classes. You instead create additional classes that control the behavior of your web client and invoke its proxy methods.

Web Client Architecture

To understand how an InterSystems IRIS web client works, we follow the events that occur when a user or other agent invokes a method within the web client.

  1. First the web client creates a SOAP message that represents the method call and its argument values.

  2. Next it creates an HTTP request that includes the SOAP message. The HTTP request includes a request line and HTTP headers, as described earlier.

  3. It issues the HTTP request, sending it to the appropriate URL.

  4. It waits for the HTTP response and determines the status.

  5. It receives the SOAP response from the web service.

  6. It unpacks the SOAP response.

The following figure shows this flow:

SOAP client that creates a message and sends it to the web service over http, and then unpacks the response

Additional Features

You can add the following features to your InterSystems IRIS web services and web clients:

  • Session support. As noted earlier, although the SOAP specification does not define a standard for sessions, with InterSystems IRIS, you can create client-server SOAP sessions.

  • Custom SOAP headers (including WS-Addressing headers), custom SOAP message bodies, and custom SOAP faults.

  • MIME attachments.

  • Use of MTOM (Message Transmission Optimization Mechanism).

  • Authentication (user login) between a web client and a web service, as well as key parts of the WS-Security standard.

  • Policies, which can control how the service or client do the following:

    • Specify the WS-Security header elements to use or to require.

    • Specify the use of MTOM.

    • Specify the use of WS-Addressing.

    See Securing Web Services.

  • Options to fine-tune the generated WSDL document to meet most format requirements.

  • Use of transport other than HTTP between the web client and web service.

For details on supported standards, see the next section.

SOAP Standards

This section lists the basic standards and WSDL support details for InterSystems IRIS web services and web clients.

Also see XML Standards and SOAP Security Standards.

Basic Standards

InterSystems IRIS web services and clients support the following basic standards:

WSDL Support in InterSystems IRIS

InterSystems IRIS does not support all possible WSDL documents. More flexibility is provided on the client side, because it is frequently necessary to create web clients that work with specific WSDLs that cannot be changed. This section discusses the details of the support.

Generated WSDL Documents

The WSDL documents generated by InterSystems IRIS web services do not include headers. Also, the web services that you can create in InterSystems IRIS do not reflect all possible variations.

Note that the SOAP specifications do not require a web service to generate a WSDL at all.

Consuming WSDLs

The InterSystems IRIS SOAP Wizard cannot process all possible WSDL documents. In particular:

  • It does not support the <fault> element. That is, if you include a <fault> element within the <operation> element of the binding, the <fault> element is ignored.

  • For the response messages, one of the following must be true:

    • Each response message must be in the same namespace as the corresponding request message.

    • The response messages must all be in the same namespace as each other (which can be different from the namespaces used by request messages).

  • The InterSystems IRIS SOAP Wizard does not process headers of the WSDL.

The SOAP Wizard does allow the use of the MIME binding in a WSDL (https://www.w3.org/TR/wsdl#_Toc492291084Opens in a new tab). The MIME parts are ignored and the remainder of the WSDL is processed. When you create a web service or client based on a WSDL that contains MIME binding, you must add explicit ObjectScript code to support the MIME attachments; this task is beyond the scope of this documentation.

Key Points about the SAX Parser

The InterSystems IRIS SAX parser is used whenever InterSystems IRIS receives a SOAP message. It is useful to know its default behavior. Among other tasks, the parser does the following:

  • It verifies whether the XML document is well-formed.

  • It attempts to validate the document, using the given schema or DTD.

    Here it is useful to remember that a schema can contain <import> and <include> elements that refer to other schemas. For example:

    <xsd:import namespace="target-namespace-of-the-importing-schema"
                  schemaLocation="uri-of-the-schema"/>

<xsd:include schemaLocation="uri-of-the-schema"/>

    The validation fails unless these other schemas are available to the parser. Especially with WSDL documents, it is sometimes necessary to download all the schemas and edit the primary schema to use the corrected locations.

  • It attempts to resolve all entities, including all external entities. (Other XML parsers do this as well.) This process can be time-consuming, depending on their locations. In particular, Xerces uses a network accessor to resolve some URLs, and the implementation uses blocking I/O. Consequently, there is no timeout and network fetches can hang in error conditions, which have been rare in practice.

    If needed, you can create custom entity resolvers; see Customizing How the SAX Parser Is Used in Using XML Tools.

Next sectionCreating Web Services
FeedbackOpens in a new tab