Creating Custom Apex SOAP Web Services
With SOAP Web services, you can create higher-level APIs of your own directly in the Force.com platform and invoke them from your own programs outside of Force. Your custom SOAP services can bundle a series of related queries or updates into a single call, providing an atomic unit of work and reducing network traffic and API call consumption.
Caution
Custom SOAP services run with administrative rights by default, granting your Apex code access to all data in the organization.
One way to understand the value of Apex SOAP Web services is to first examine limitations in the Enterprise API. The Enterprise API is a direct representation of the objects in your database as SOAP message types, with methods to query and modify them per record or in batches. This low-level access to the Force.com database through standard protocols and messages opens your Force.com applications to the outside world but isn’t perfect for every integration scenario. The following list points out some areas in which the Enterprise API can fall short:
Transactions—There is limited support in the Enterprise API for transactions that span multiple objects. If an external program must modify many objects in an atomic operation, it needs to detect failure for each call and apply a compensating action to reverse prior successes.
Integrated security—The Enterprise API always applies object-, field-, and record-level sharing rules of the currently logged-in user. This cannot be disabled by an external program calling into Force.com. If greater rights are needed, an administrator must alter the user’s profile or the program must log in with the credentials of a more privileged user. This can complicate integration programs by requiring many logins of varying privileges or put the organization at risk by running integration programs with administrative rights.
Performance—As your integration programs get more complex, they can become chatty, making many calls to Force.com to fetch different types of records and postprocess them off-platform. This consumes more of the API calls toward the organization’s daily limit and reduces performance by putting more data on the wire.
The definition of a custom SOAP service is slightly different from that of a regular Apex class. The differences are listed here:
Global class access modifier—A class that contains any SOAP services must use the global access modifier. This means the class is visible to all programs running in the Force.com organization.
SOAP methods—Each method accessible via SOAP must be defined with the webservice keyword. These methods must also be static.
Security—SOAP methods run as a system administrator, without regard for object-, field-, or record-level sharing rules. To enforce record sharing rules, define the class with the with sharing keyword. To enforce object- and field-level security, use the results of the getDescribe method (Schema.DescribeSObjectResult and Schema.DescribeFieldResult) to check the user’s permission to the data.
Supporting classes—User-defined Apex classes, inner or outer, that are arguments or return values for a SOAP service method must be defined as global. Member variables of these classes must be defined using the webservice keyword.
No overloading—SOAP service methods cannot be overloaded. Overloaded methods result in a compile error.
Prohibited types—The Map, Set, Pattern, Matcher, Exception, and Enum types are not allowed in the arguments or return types of Apex SOAP services.
Additionally, SOAP services written in Apex must abide by its governor limits. A subset of these governor limits is listed in Table 10.3.
Listing 10.20 defines a simple Apex SOAP service that creates a record in the Project custom object given a name.
Listing 10.20 Sample Apex Code for Custom SOAP Service
global class Listing10_20 {
webservice static ID createProject(String name) {
Project__c proj = new Project__c(Name = name);
insert proj;
return proj.Id;
}
}
Calling an Apex SOAP Service
To call an Apex SOAP service from client code, follow these steps:
1. In the App Setup area, click Develop, Apex Classes.
2. Locate the class containing the Apex SOAP service and click the WSDL link.
3. Save the WSDL on your local file system. You’ll need this plus the Enterprise WSDL in order to call the custom Apex SOAP service.
4. Generate stub code from the custom WSDL and add it to your project.
5. Authenticate using the Enterprise WSDL by passing a ConnectorConfig to Connector.newConnection method; then change the service endpoint to the one from the custom WSDL.
6. Create a new SoapConnection from the ConnectorConfig, and invoke the custom Apex SOAP service method.
Listing 10.21 demonstrates the invocation of the custom createProject service in Java using the WSC, with the stub code generated to a .jar file named Listing10_20.
Listing 10.21 Java Fragment for Invoking Custom Apex SOAP Service
ConnectorConfig config = new ConnectorConfig();
config.setUsername(user);
config.setPassword(pass);
Connector.newConnection(config);
config.setServiceEndpoint(com.sforce.soap.Listing10_20.Connector.END_POINT);
SoapConnection sconn = new SoapConnection(config);
String projectId = sconn.createProject("Test Project");