InterSystems IRIS® data platform 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.
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:
The request is received by a third-party web server.
Because the request is directed to a URL that ends with .cls, the web server forwards the request to the Web Gateway.
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.
When the web service page receives the request, it invokes its OnPage() method.
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.
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.
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.
The web service executes the requested InterSystems IRIS method, packages up the reply, and constructs a SOAP response, including a SOAP header if appropriate.
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:
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.
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.
First the web client creates a SOAP message that represents the method call and its argument values.
Next it creates an HTTP request that includes the SOAP message. The HTTP request includes a request line and HTTP headers, as described earlier.
It issues the HTTP request, sending it to the appropriate URL.
It waits for the HTTP response and determines the status.
It receives the SOAP response from the web service.
It unpacks the SOAP response.
The following figure shows this flow: