Understanding Force.com SOAP API
Force.com SOAP API allows data, logic, and metadata to be accessed from outside the Force.com platform by any program that can communicate using SOAP messages over HTTP. With a strongly typed language like Java or C#.NET, stub code is generated from the Force.com SOAP API’s WSDL. The program must log in to Force.com to establish a session and can then invoke the SOAP API methods.
This section describes concepts that can be applied to using any Force.com SOAP API method. It consists of the following parts:
Basics of Force.com SOAP API—Learn about the two different styles of Force.com SOAP API methods, how they are secured, and limits placed on their use.
Generating stub code—Walk through the process for generating Java code from Force.com SOAP API WSDL.
Logging in—The first SOAP API call typically establishes a session with Force.com by logging in. This session is used to make subsequent SOAP API calls until it is invalidated explicitly or it expires.
Force.com data types in SOAP—Understand how data types in Force.com objects are expressed in the SOAP API.
Error handling—Force.com SOAP API signals errors in a few ways, depending on where the errors originate.
Basics of Force.com SOAP API
The Force.com SOAP API comes in two forms, Enterprise and Partner. Both APIs have the same core set of calls, such as query to execute a SOQL query. The difference between the APIs is how database objects are represented in your code.
The Enterprise API provides a strongly typed representation of the objects in your Force.com database. This allows your code to operate naturally with Force.com data, using the field names and data types as you would in Apex code. When you redefine an object or add a new object, the Enterprise WSDL is automatically updated to reflect the changes. You need to manually regenerate the client code from the latest WSDL, but this is a small price to pay for concise, maintainable code.
The Partner API is designed for independent software vendors who write applications that must interoperate with many different Force.com organizations. They cannot rely on a single, static representation of standard and custom objects because all customers of Force.com are free to create their own database schemas. With the Partner API, you can write generic code to access any object in any Force.com organization. It’s more verbose to work with than the Enterprise API, but more flexible as well.
Note
This book does not cover the Partner API. For more information about it, consult the Force.com SOAP API Developer’s Guide, available at www.salesforce.com/us/developer/docs/api/index.htm.
Versions
With each major release of the Force.com platform, new versions of its WSDL are also released. To take advantage of new features, your code must be updated to use the latest WSDL.
If the new features are not needed, no action is required. Your code will continue to work without modification. This is because each WSDL has an endpoint URL in it that includes its version.
In its documentation, Salesforce commits to maintaining Web service versions for a minimum of three years. It also states that one year of notice will be provided for discontinued Web service versions.
Security
Force.com uses Secure Sockets Layer (SSL) v3 and Transport Layer Security (TLS) to protect the communications between your client application and the Force.com platform.
After your client program has logged in, all the API calls respect the full set of data security features in Force.com at the object, field, and record level. For this reason, configuring a Force.com profile and user account dedicated solely to integration is a good practice. It might have elevated privileges compared with other, Web-based users. You can configure this profile to accept logins only from the API address of your corporate integration server using the Login IP Ranges on the profile or logins at specific times that your integration is scheduled to run using the Login Hours section.
API Limits
Salesforce limits the number of API calls that can be executed during a 24-hour period. Every call into Force.com is counted against this limit, including calls made by the Force.com IDE. The exact limit depends on the edition of Force.com you have licensed.
To view your API limit and current consumption, go to the Administration Setup area and click Company Profile, Company Information. You can configure Force.com to email you when your organization is close to its API call limit. Go to the Administration Setup area and click Monitoring, API Usage Notifications. Click the New button to define a new notification, specifying the user to receive the notification, the usage threshold that triggers notifications, and how often they are sent.
Generating Stub Code
If you’re using a strongly typed language like C#.NET or Java to integrate with Force.com, your first step is to generate stub code from a Force.com WSDL. All standard Force.com WSDLs are available in the App Setup area; to access them, click Develop, API. Click each WSDL link and save the resulting document on your local file system.
Each language and development tool typically provides a facility for parsing WSDL and generating stub code that can be incorporated into your program. The steps for generating Java stub code from WSDL are described next.
Note
Salesforce advises that you use the Force.com Web Service Connector (WSC) with its SOAP API. Download it from https://github.com/forcedotcom/wsc. Download the source code from https://github.com/forcedotcom/wsc. Follow the instructions there to compile the source code into a WSC JAR file, which requires Maven (http://maven.apache.org/). If you would rather download a WSC JAR file than build it, find one at http://code.google.com/p/sfdc-wsc/downloads/list.
Follow these steps to create Java stub code using WSC and the Eclipse IDE:
1. Create a new Java project. In this example, the project is named Chapter10.
2. Copy the WSC jar and enterprise.wsdl files into the top level of your Java project.
3. Create a new Run Configuration to execute the stub generator. Figure 10.2 shows the Run Configuration.
4. Click the Arguments tab and enter enterprise.wsdl.xml ./enterprise.jar in the Program Arguments text box. These arguments tell the program to generate the stub code for the enterprise.xml.wsdl file into a jar named enterprise.jar.
5. Click the Run button on the Run Configuration and refresh your project. It should contain the stub code for the Force.com Enterprise API, as depicted in Figure 10.3.
Logging In
Logging in to Force.com from a program begins with the user credentials of username and password, the same as logging in to the native user interface using a Web browser. This subsection describes four additional details to be aware of to successfully log in, summarized here:
API Enabled permission—The user logging in must have the API Enabled permission on his or her profile.
Security token or white-listed IP address—Force.com requires either a security token appended to the password or API calls to be issued from a white-listed IP address.
Login call—When successful, the login method returns two items of information needed in subsequent calls: a URL to the Salesforce server and the user’s session identifier.
Troubleshooting login problems—Force.com includes a Login History report that can be helpful in identifying problems.
API Enabled Permission
The user logging in via API must have the API Enabled permission set on his or her profile. This permission is found in the Administrative Permissions section. A profile with the API Enabled permission is shown in Figure 10.4.
Caution
A few editions of Force.com don’t allow API access. If you don’t see the API Enabled permission on the profile page or cannot enable it, contact Salesforce support.
Security Token or White-Listed IP Address
The security token is a string of characters appended to the end of a user’s password. It allows a user to log in to Force.com from any IP address, assuming that IP address restrictions are not configured on his or her profile. To obtain a security token, visit the Personal Setup area and click My Personal Information, Reset My Security Token. A new security token is generated and emailed to the address associated with the user.
An alternative to security tokens is IP white-listing. White-listing instructs Force.com to accept requests from a specific IP address. To white-list an IP address, go to the Administration Setup area and click Security Controls, Network Access. Click the New button, enter the IP address in the Start IP Address and End IP Address fields, and then click the Save button.
The Login Call
To log in, invoke the login method with a username and password. If the login is successful, a LoginResult object is returned; otherwise, an exception is raised. The LoginResult object contains the URL of the server to send SOAP API requests to and the session identifier that uniquely identifies your authenticated session with Force.com. Both of these attributes must be sent in the HTTP headers of subsequent requests for them to succeed.
Listing 10.16 contains sample Java code to log in. Note that WSC takes care of the details described earlier for logging in, but this is not the case if you use a different Web service stack, such as Apache Axis.
Note
The code in Listing 10.16 doesn’t include exception handling or importing the generated stub code. It also doesn’t factor in the use of corporate proxies, which might block outbound HTTPS traffic. Java can be configured to pass connections through a proxy. If your connections to Force.com are failing, check with your network administrator to see whether a proxy could be the cause.
Listing 10.16 Java Fragment to Log In
ConnectorConfig config = new ConnectorConfig();
config.setUsername(user);
config.setPassword(pass);
EnterpriseConnection connection = Connector.newConnection(config);
When you’re done with a session, you can invoke the logout API call. It causes the session to become invalid, ensuring that it is not used accidentally elsewhere by your program.
By default, sessions expire after two hours, but you can change this in the Administration Setup area by clicking Security Controls, Session Settings. Web service calls that use an expired or invalid session throw an exception with an INVALID_SESSION_ID exception code.
Troubleshooting Login Problems
All logins to Force.com create an entry in the login history, shown in Figure 10.5. To view it, go to the Administration Setup area and click Manage Users, Login History.
The login history can be helpful for troubleshooting login problems. If you see your program’s login attempt listed but failed, the login request has successfully reached Force.com’s servers but is being rejected. If the request is not listed at all, you need to investigate the connection between your server and Force.com.
Force.com Data Types in SOAP
Table 10.2 lists the Force.com data types and their mapping to SOAP data types.
Refer to the documentation for your programming language or SOAP utility library to map SOAP types to language-specific data types.
Error Handling
Three categories of errors are raised by Force.com SOAP API, described here from lowest to highest level of abstraction:
1. System exceptions—System exceptions are language-specific and indicate lower-level problems occurring in the Web services stack. For example, using Java with the WSC, the ConnectionException contains nested exceptions to indicate specific problems, such as a java.net.SocketException.
2. API faults—API faults are caused by malformed SOAP messages, authentication failures, or query-related problems. They are SOAP-level errors that contain an exception code and a message. For example, in Java, a LoginFault class extends ApiFault and indicates that the login to Force.com failed. A general API fault with an exception code of INSUFFICIENT_ACCESS indicates that the user does not have sufficient access to perform the operation.
3. Application errors—These are language-neutral, Force.com-specific errors that vary based on the Web services involved. For example, services that modify one or more records return an Error object upon failure. The Error object contains a status code, a message, and an array of fields impacted by the error. As a concrete example, if your record modification violates the referential integrity of the Force.com database, an Error object containing FIELD_INTEGRITY_EXCEPTION as its status code is returned.