Basic Requirements

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 ]
```

By default, any inherited methods are treated as ordinary methods, even if a superclass marks them as web methods (but see Subclassing an Existing InterSystems IRIS Web Services).

Input and Output Objects That Do Not Need %XML.Adaptor

In most cases, when you use an object as input or output to a web method, that object must extend %XML.AdaptorOpens in a new tab. The exceptions are as follows:

If the object is %ListOfDataTypesOpens in a new tab, %ListOfObjectsOpens in a new tab, %ArrayOfDataTypesOpens in a new tab, %ArrayOfObjectsOpens in a new tab, or a subclass, the InterSystems IRIS SOAP support implicitly treats the object as if it included %XML.AdaptorOpens in a new tab. You do not need to subclass these classes. However:
- You must specify ELEMENTTYPE within the method signature, as follows:
```
Method MyMethod() As %ListOfObjects(ELEMENTTYPE="MyApp.MyXMLType") [WebMethod]
{
   //method implementation
}
```
  Or, in the case of an input argument:
```
Method MyMethod(input As %ListOfObjects(ELEMENTTYPE="MyApp.MyXMLType")) [WebMethod]
{
   //method implementation
}
```
- If the class that you name in ELEMENTTYPE is an object class, it must inherit from %XML.AdaptorOpens in a new tab.
If the object is one of the stream classes, the InterSystems IRIS SOAP support implicitly treats the object as if it included %XML.AdaptorOpens in a new tab. You do not need to subclass the stream class.
If it is a character stream, the InterSystems IRIS SOAP tools assume that the type is string. If it is a binary stream, the tools treat it as base-64–encoded data. Thus it is not necessary to supply type information.

Using Result Sets as Input or Output

You can use result sets as input or output, but your approach depends on the intended web clients.

If both the web service and client are based on InterSystems IRIS or one is based on .NET, you can use the specialized result set class, %XML.DataSetOpens in a new tab, which is discussed in Using Datasets in SOAP Messages. Or you can use a class query as a web method. The XML representation is automatically the same as for %XML.DataSetOpens in a new tab.
To output results of a query so that a Java-based web client can work with it, use a %ListOfObjectsOpens in a new tab subclass.

Simple Example

Overview of InterSystems IRIS Web Services