To create a web service in InterSystems IRIS, create and compile an InterSystems IRIS class that meets the following basic requirements:
-
The class must extend %SOAP.WebServiceOpens in a new tab.
-
The class must define the SERVICENAME parameter. InterSystems IRIS does not compile the class unless it defines this parameter.
-
This class should define methods or class queries that are marked with the WebMethod keyword.
Important:
In most cases, web methods should be instance methods. Within a web method, it is often necessary to set properties of and invoke methods of the web service instance (as described in later topics) to fine-tune the behavior of the method. Because a class method cannot do these tasks, a class method is usually not suitable as a web method.
-
For any web methods, make sure that each value in the method signature has an XML projection. For example, suppose that your method had the following signature:
Method MyWebMethod(myarg as ClassA) as ClassB [ WebMethod ]
In this case, both ClassA and ClassB must have an XML representation. In most cases, this means that their superclass lists must include %XML.AdaptorOpens in a new tab; see Projecting Objects to XML. InterSystems IRIS SOAP support provides special handling for collections and streams, as noted after this list.
The web method can specify the ByRef and Output keywords in the same way that ordinary methods do. (For information on these keywords, see Methods.)
-
Consider the values that are likely to be carried within these arguments and return values. XML does not permit nonprinting characters, specifically characters below ASCII 32 (except for carriage returns, line feeds, and tabs, which are permitted in XML).
If you need to include any disallowed nonprinting character, specify the type as %BinaryOpens in a new tab, %xsd.base64BinaryOpens in a new tab (which is equivalent), or a subclass. This value is automatically converted to base–64 encoding on export to XML (or automatically converted from base–64 encoding on import).
-
Do not rely on the method signature to specify the default value for an argument. If you do, the default value is ignored and a null string is used instead. For example, consider the following method:
Method TestDefaults(val As %String = "Default String") As %String [ WebMethod ]
When you invoke this method as a web method, if you do not supply an argument, a null string is used, and the value "Default String" is ignored.
Instead, at the start of the method implementation, test for a value and use the desired default if applicable. One technique is as follows:
if arg="" {
set arg="Default String"
}
You can indicate the default value in the method signature as usual, but this is purely for informational purposes and does not affect the SOAP messages.
-
For any required arguments in a web method, specify the REQUIRED property parameter within the method signature. For example:
Method MyWebMethod(myarg as ClassA(REQUIRED=1)) as ClassB [ WebMethod ]