« June 2006 | Main | August 2006 »

July 31, 2006

ruby force...

Try out the ruby connector to use the salesforce API in ruby.

Posted by Chris at 09:55 PM

July 29, 2006

Salesforce API traffic due to lack of joins?

My API post got a little reaction here at the heretic site. One of his points is that we need a way to create more complex queries that allow you to aggregate data before you return it to the client. I couldn't agree more. This is one of our most frequently requested API features. I can't promise anything but you should be able to do this in an upcoming release.

Posted by Chris at 09:23 PM

Stax is part of JEE 5.0

Stax (JSR 173) is now part of JEE 5.0, it got a nice congratulations post here , thanks Mike. The whole reason this api exists is so you don't have to create a strange inversion of control architecture to parse XML. You drive the XML parser it doesn't drive you.

Posted by Chris at 09:19 PM

July 28, 2006

Why over 40% of Salesforce.com’s traffic is Web Services

I wrote this article when I started at Salesforce, with the intention of publishing it somewhere on the web.

Salesforce.com has designed one of the web’s most successful Web Services. More than 40% of the site’s traffic and over 10 million calls a day come through Web Services. This article discusses the design principles behind the Salesforce.com Web Service API , features of the API itself, gives examples of how to use it, and considers the future of service-based infrastructure.

Enterprise Software as a Service

Businesses are starting to realize the benefits of software as a service. Although businesses have been outsourcing functionality for years, they are now replacing packaged software with internet services that provide equivalent or better features and functionality. This is happening for several reasons:

• Up-front costs are low and customers pay for just what they use.
• Operating costs are reduced because the infrastructure is built-out by the service provider.
• It is cheaper for the software producer to create the software because there is only one environment (no porting required) allowing more resources to focus on application enhancements.
• There is no need to go through costly upgrades.
• Recent messaging standards (WSDL/SOAP) allow easy data integration with remote services.

These benefits and more are discussed in [1]. The success of Salesforce.com in the CRM (Customer Relationship Management) market and as an application platform has been driven by many of the above factors. One of the key factors driving Salesforce.com’s success is a Web Service API that allows businesses to integrate with data remotely and automatically.

Hosted CRM
Remote and automated access
Some of the most successful services on the web today never result in a web page being rendered on a browser. Instead they involve automated communication between computers. For a user of an on-demand service it is crucial to be able to retrieve data and synchronize it with other clients such as email and calendaring programs and repositories like SAP. The huge growth of Salesforce.com’s online application has driven corresponding growth in the associated Web Service API which allows programmatic access to all user data in the system.

Customers and partners use the API to integrate and extend Salesforce.com’s hosted CRM solution to provide new application functionality. Examples include mirroring data, bulk data transfer, data cleansing, and various other custom functionality. It is possible to use the customization properties of the Salesforce.com application and the API to create completely new internet-ready applications. Several key design decisions and design principles have governed the creation of this API and are discussed in the next section.

API Design
Designing an API that functions on the scale of the internet involves following a set of design principles. This section describes the principles that drive a successful web service: 1) KISS (Keep it Simple, Stupid); 2) No new verbs / REST; 3) Design for scalability & backwards compatibility; 4) Be open 5) Dog-Fooding. The first section describes the principles and the second talks about how these have been used to guide the design of the Salesforce.com API.

General Design Strategies

A well-designed API is simple, intuitive and easy to use. It uses only the constructs needed, has no unnecessary constraints or operations. The method names should be succinct and have no unknown side effects. With little or no documentation someone should be able to write a “Hello World” style example. Strong-typing should be used to clearly communicate the structures that interact with the API verbs. Generic data structures can be used to provide a more powerful API that allows programs to operate on meta-data to create generic tools. Some of the best designs allow programmers to choose when they want the compile-time type checking of strong typing or the power of a generic programming style.

REST (Representational State Transfer)[3] is an architectural style that describes how the internet operates at the highest level. People typically associate REST with HTTP/XML and URLs. In a typical REST system the URLs define the location of the resources, the XML defines the resource state and HTTP defines the methods that operate on the state (basically HTTP POST and HTTP GET). Verbs are the operations that act on data in an API. Objects or nouns are retrieved but not modified by referring to their URL using a GET. The state can be modified and put back with a POST. This same style of interaction can be enabled with WSDL and SOAP. Although REST is typically associated with HTTP and XML these technologies are not required for implementing a RESTful service. Limiting the number of verbs in the system makes it easier to upgrade and add new functionality.

Backwards compatibility and scalability are crucial with an on-demand service as customers do not control when they receive new versions of the service and may be sharing computational infrastructure. Compatibility can be guaranteed by keeping previous versions intact in a parallel runtime environment.

‘Being open’ means using standards where possible and allowing free access to data in the application. Standards provide an ecosystem that supports knowledge transfer, investment protection and interoperability. They give developers the ability to apply tricks learned elsewhere on a current product. Consumers are free to choose among competing standard implementations. Finally by focusing on standard wire-level protocols different products can interoperate and integrate.

Dog-fooding is the practice of using a software product to build or test itself (“Eating your own dogfood”). Although not specific to API design it’s a good practice in general for creating quality products.

The Salesforce.com API
This section describes how the Salesforce.com API was designed following the above principles.

The Salesforce.com API provides a simple way to set and get application data. Creating a client application is a very short process using Java or .NET Web Service tools. WSDLs that describe services in the API can be either strongly or weakly typed against user data. Users have the option of creating a WSDL that will describe their custom objects in XML Schema. This is done automatically for each customer, and called the Enterprise WSDL. Objects are always available using the generic methods but it’s often easier to write integrations that have compile-time type checking. Modern development tools with code completion work well with strongly typed WSDLs. A loosely-typed WSDL would work for all customers, however Salesforce.com maintains custom WSDL files for each customer so that it’s easier to program using tools such as Visual Studio, Eclipse, IntelliJ , and others.

To retrieve data, Salesforce designed a language called SOQL (Salesforce Object Query Language). This looks similar to SQL, a language almost all enterprise programmers are familiar with. This language is most like object-query languages like hibernates HQL.

Since REST is an architectural style and not a set of technologies, it is possible to create a REST-like API that uses XML to define the state and WSDL operations to define the put and get operations. The main operations are retrieve, create, update, query and delete. All these operations work on objects or arrays of objects. Retrieve allows you to retrieve an object based on its ID. The object IDs are globally unique in the system and uniquely identify an object.

These methods, unique IDs and object state result in a RESTful system of named resources (objects), that are processed using a generic, uniform interface, and are interconnected using unique IDs to allow navigation. In general Salesforce.com tries to rarely add verbs and rely on only additive changes to the metadata for backward compatibility. Client code rarely has to deal with new verbs, allowing customers to upgrade to new versions with little or no modifications to their code.

Backwards compatibility is guaranteed by versioning the service and keeping old API stacks running. The new versions run side-by-side with the old versions, allowing existing integrations to continue running with no side-effects of code change after a service upgrade. Each SOAP message contains the specific version of the service that it is addressing allowing the server side to adapt its behavior based on API version. Clients are designed to support additive changes to the nouns, allowing existing integrations to seamlessly move forward to new API versions to take advantage of performance and/or functionality enhancements.

Salesforce.com handles more than 10 million calls a day through its web service API. Traffic of this magnitude requires an efficient and scalable processing platform. All calls to the API are stateless but have an associated session ID that allows the server to correlate state with the request. Methods are designed to execute quickly and to return large datasets in chunks. The API is designed to chunk data into blocks on the server side allowing the client code to cursor over the data.

Salesforce.com adheres to web services standards. The service is tested against WS-I BP 1.1 to ensure compatibility. Additionally, documentation, free trial accounts and community messages boards are all available for free at sforce.com. This ensures the API works with all tools that support web services.

Salesforce.com has a long history of incremental, adaptive, improvement. This is summarized in [4] . One of the keys to the API’s success is that it drives a large percentage of backend testing and has aided incremental development. Testing a website is often hard and labor intensive, however by testing the site with the API Salesforce.com has been able to automate much of the testing of the platform.

Using the API
This section describes the main features of the API and gives examples in Java of how to invoke and use the Salesforce application through the API. Other examples can be found at the sforce developer site [2]. These examples were built using Axis 1.2 and JDK 1.5 using the enterprise WSDL from a test organization on the Winter 06 release.
The API provides a SOAP/WSDL interface that allows people to create, modify and delete objects using XML over HTTP. It allows programs to search using SOSL (Salesforce Object Search Language) and query using SOQL (a SQL like query language, Salesforce Object Query Language). The main verbs are retrieve, create, update, query and delete.

Access to the data exposed by the API is governed by the permissions and security options available in the application. All interactions with the service are encrypted using SSL. Client applications must log in using valid credentials for a Salesforce account. The Sforce server authenticates these credentials and, if valid, provides the client application with:
• A sessionID that must be set into the session header so that all subsequent API calls are authenticated
• A URL for the Sforce Web service that will service the client application's Web service requests

Service Description
A service is described using either the Partner WSDL or the Enterprise WSDL. The Partner WSDL is generic and applies to all services, describing the operations and generic data objects that exist in the Salesforce application. The Enterprise WSDL is generated per organization and includes XML Schema descriptions of custom objects.

Getting Started
Inside the Salesforce.com application go to Setup → Integrate → WSDL Generator → Download Enterprise WSDL. Download the WSDL and use your favorite WSDL compiler to generate client code.
The following code illustrates how to login into the API. You will have to use a valid salesforce account and replace and with your credentials. You can sign up for a developer edition account for free so it’s very easy to try out the service and test code against the API.

	// Make a service
	SforceService service = new SforceServiceLocator();

// Now use the service to get a stub which implements the SDI.
SoapBindingStub port = (SoapBindingStub) service.getSoap();

LoginResult loginResult=null;
int loginCount=0;
while(loginCount <= 3) {
try {
loginResult = port.login(,);
} catch (com.sforce.soap.enterprise.fault.LoginFault lf) {
throw lf;
} catch (RemoteException e) {
if (loginCount >= 3) {
throw new Exception("Unable to login to Salesforce after "+loginCount+
" tries\n Underlying exception=["+e.getMessage()+"]");

The above code manages logging into the API. The login call returns an endpoint and a session header that needs to be included on all subsequent API calls in the current session.


SessionHeader sh = new SessionHeader();

//set the session header for subsequent call authentication
port.setHeader(service.getServiceName().getNamespaceURI(), "SessionHeader", sh);
// Make the actual call
" Invoked timestamp is:"

The following query illustrates how to get information out of the API using SOQL and a cursor across a result set.

	QueryResult qr = null;
	try {
	    qr = port.query("select firstname,lastname from contact");
	    boolean done = false;
	    if (qr.getSize() > 0){
		System.out.println("Logged in user can see " + 
qr.getRecords().length + " contact records.");
		while (!done) {
		    for (int i=0;i

Insert and Update
The following code shows how to create and insert a new Account object into the system.

Account account1 = new Account();
account1.setName("Acme International");
account1.setBillingStreet("4322 Haystack Boulevard");
SObject[] sObjects = new SObject[1];
sObjects[0] = account1;
SaveResult[] saveResults = port.create(sObjects);

for (int i=0;i // Determine whether create succeeded or had errors
if (saveResults[i].isSuccess()) {
// No errors, so we will retrieve the id created for this index
else {
// Handle the errors

The following code shows how to update an object given its ID.

   SObject[] updates = new SObject[1]; 
   Account updateAccount = new Account(); 
   updateAccount.setName("New Account Name from Update Sample"); 
   updates[0] = updateAccount; 
   SaveResult[] updateResults = port.update(updates);
More resources More resources can be found at http://www.sforce.com , including comprehensive API documentation and support forums for developers.

Looking Forward
This section describes some of the features of the API that may be coming in future versions of the Salesforce.com platform. These statements are forward looking and may or may not reflect future versions of the Salesforce.com API.

• Relationships
• Reliable Messaging
• Outbound calls
• MetaData API
• Single Sign On for Web Services

Relationships allow users to query across a set of objects and their relationships. This is a much requested feature in the API and allows a single query to simulate joining against various backend object relationships. Currently client code is required to do the join on the client by executing multiple queries and matching on the ID’s of the objects.

Reliable outbound messaging represents a way for client applications to be notified when information changes rather than having to poll the application for state changes.

Finally, a MetaData API allows consumers and producers of applications built on the AppForce platform to automatically export application metadata and to write programs that automatically install and configure applications.

What does this mean for Web Services?

Salesforce is at the forefront of Web Service technology. It drives the core of its business using SOAP and WSDL. Many people suggest that Web Services need time to mature however salesforce.com has shown that using simple design principles you can build your business on Web Services today and don’t need to wait for WS-* to get things done.

Currently Web Services enable wide scale integration for hosted services platforms. As more and more software moves to the on-demand model Web Services will provide the protocols that let companies and individuals access their data. The current set of Web Service technologies are enough to make progress today and build successful integrations. As these integrations are built out they will drive standards around sessions, reliable messaging, asynchronous messaging and usable security models.

[1] Dean Jacobs, Enterprise Software as a Service, ACM Queue vol. 3, no. 6 - July/August 2005
[2] http://www.sforce.com
[3] http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
[4] http://salesforce.breezecentral.com/intelligentreaction/

Posted by Chris at 01:32 PM

July 16, 2006

Purple Haze

Three weeks ago I ordered a new Haut 9'6 longboard. It's a great experience to order a custom surfboard, they build it for your height and your shape and you get to pick the glass job and the air brushed design. I was in the Haut shop 5 weeks ago and my friend Paul bought a really nice 9' board. I had to admit my raw jealousy and just go buy one so I wouldn't continue to covet Paul's board. I have been surfing a 9' Haut epoxy board for some time but I realized that the epoxy boards have too much flotation and don't slice the wave as nicely as a traditional longboard.

This fin was picked out by the guy working in the shop, his quiote: "it's like it was made exactly for your board."

Getting a custom shaped board made me realize how the master craftsman isn't very common in America any more. However surfboards are still a hand shaped piece of art that you can own for a pretty affordable price.

Today Reed (photo's are courtesy of Reed Foster) and I took the board out at Cowell's beach in Santa Cruz. It was a beautiful day but my board got dinged when some kook ran into it. When my wife saw the board she said it looked like a bowling ball, ouch!

My favorite spot to surf in SC is 41st street, this is the report . Can't wait to take the 'purple haze' out there.


Order No: 26140
Size: 9'6
Design: Single Fin, H46 Walker, 18 1/2 NOSE, 23 1/2 WIDE, 14 3/4 TAIL, 3 1/4 THICK, SQUARE Tail
Glassing: Purple acid splash, Bottom to rails, clear deck, standard glassing
Fin: Single Box


Posted by Chris at 09:57 PM

July 12, 2006

Sam moves on

Sam has decided to move on to yahoo, I hope he has fun there!

Posted by Chris at 10:45 AM

July 11, 2006


The new pullitzer prize winner is out, and it is: March. I'll post a review when I finish.

Posted by Chris at 09:34 AM