spikes

Creating your first Apex Code

One of the amazing things that is going on at Salesforce right now is we are creating our own on demand programming language. It's really easy to create a Hello World example using Apex Code in Salesforce. Right now you can create your own custom web service by simply putting the key word 'WebService' in front of your method.

1) To make this work you just need an Apex Code enabled DE org.

2) read these docs

http://www.salesforce.com/us/developer/docs/apexcode/salesforce_apex_language_reference.pdf

Instead of doing the extended example in the docs create a simple hello world apex example. Here is the code:

package myFirstPackage {
webService String helloWorld(String name){
return 'Hello '+name;
}
}

3) Now install the Ajax Toolkit in your DE org

http://www.salesforce.com/appexchange/detail_overview.jsp?id=a0330000002foeKAAQ&NavCode__c=

4) And go into your DE org and execute it, you get a nice UI to edit and execute your example. This link will give you help on using the Ajax toolkit

http://wiki.apexdevnet.com/index.php/Ajax_Tools

That's it for HelloWorld running server side inside the Apex Platform.

Contract driven communication

Pete, Manoj, Alex and I went for coffee today. It was just after we had spent a couple hours testing the new version of Salesforce.com that we are getting ready to deploy. One of the topics that Pete has been talking about lately is contract driven services, should they be client driven or server driven?

He had a key insight today which is: although our service is server contract driven, our query languages (SOQL/SOSL) force/allow clients to declare what data and fields the client is interested in. "SELECT * FROM account" is illegal, but "SELECT id,name FROM account" is legal.

So clients must declare what data they are interested in. The server defines the total space of data but the client can protect itself from additive changes to the data objects by directly requesting the objects and fields.

So we have a very flexible client driven, server declared contract system.

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.

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.

Security
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.
Login
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(,);

		break;

	    } 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()+"]");

		}

		loginCount++;

	    }

	}

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.



	port._setProperty(SoapBindingStub.ENDPOINT_ADDRESS_PROPERTY, 

			  loginResult.getServerUrl());

	SessionHeader sh = new SessionHeader(); 

	sh.setSessionId(loginResult.getSessionId()); 

 

	//set the session header for subsequent call authentication 

	port.setHeader(service.getServiceName().getNamespaceURI(), "SessionHeader", sh); 

	// Make the actual call

	System.out.println("URL:"+loginResult.getServerUrl()+

                           " Invoked timestamp is:"

                           +port.getServerTimestamp().getTimestamp());

Query
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.");
		System.out.println("FirstName\tLastName");
		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.setAccountNumber("002DF99ELK9"); 

    account1.setName("Acme International");

    account1.setBillingCity("Wichita"); 

    account1.setBillingCountry("US"); 

    account1.setBillingState("KA"); 

    account1.setBillingStreet("4322 Haystack Boulevard"); 

    account1.setBillingPostalCode("87901"); 

    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 

         System.out.println(saveResults[i].getId()); 

      }

      else { 

	  System.out.println("error:"+

              saveResults[i].getErrors()[0].getMessage());

         // 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.setId(id);
   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.

References

[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/

Software as a service by Dean

Dean talks about software as a service.

Desktop widgets

Konfabulator was just acquired by Yahoo! to drive adoption of their web services platform. The logic is that widgets drive use of their API with a lower bar to entry.

Hosted versus shipping software

So I started my Salesforce.com job. Some of my initial impressions are that writing hosted software requires a slightly different mindset than writing packaged software. You need to be a master of all the security requirements of your customers and keeping the site running becomes part of the organizational know how.

More impressions later...

A replacement for WSDL?

Here is an interesting proposal for WSDL replacement: SMEX-D .

Extensible Services

One of the areas I've been getting interested in lately is around creating extensible web services. Dave O has a nice post at xml.com on the topic.

Overview of WSDL 2.0

A nice overview of the WSDL 2.0 spec can be found here . Some of the confusing terminology of the WSDL 1.1 spec has been clarified (Ports are now endpoints and PortTypes are now interfaces).
The message element has been moved into the XML Schema section.
We'll see how much support it starts to garner...

Are interfaces necessary for web services?

So last night Pete, John and I went over to check out Technorati's web service offering at their hackathon. One interesting question that came up for me is, "are interfaces necessary for web services." If you take a look at technorati's offering of queries they essentially paramatrize a url and then return an xml document. This is a very straightforward way to query their data. However they don't expose any WSDL (or even SOAP). Does that matter? I think for a v 1.0 service it doesn't. Maybe you need a little more documentation to get your service off the ground, and you can't use any generic client tools like .NET or JAX-RPC, to work with it. This could limit your user base. In practice, for popular services it doesn't seem to limit your popularity because nice developers tend to write language specific bindings for your service in Python, Perl, Java etc. This seems like an easy quick way for sites to get off the ground providing a broad set of query methods.

There are some drawbacks however to not having a WSDL and to not using SOAP. (1) You are bound to HTTP; (2) If you version the contract how do you notify your clients? (3) Related to 1, no SOAP Headers; (4) No public contract other than your documentation.

WebServices heating up

So It feels like web services are heating up. Google and Amazon have long standing web service APIs that get plenty of use. Here is a link to amazon's offering:

http://www.amazon.com/gp/browse.html/102-4902219-4008929?node=3435361

Sites like AllConsuming are integrating these sites.

Many startups have a WSDL/SOAP or RESTful API as a matter of course:

See technorati

and

Flikr.

It's not clear how much of the WS-* specs are being used here, but web services are clearly becoming the programmatic api to the web.

Loose coupling

For all the talk of loose coupling I'm surprised how tightly coupled WebServices have become. I think there is room for a completely interpreted stack that does no binding to the java types but enforces XMLSchema constraints and SOAP QOS for reliability, security and routing. It would be cool to implement this in python or perl and insert it as an adaptive layer between the world and the application.

Data Binding in Web Services

Often when using webservices you are confronted with a decision on how to bind the XML Schema you have into java. If you are starting with a WSDL you can either bind each complex type to a DOM or to a generated java class. Each method has its advantages and disadvantages. Fine-grained binding into java is nice if you are going to use each data type in the application, are satisfied with the default binding and are planning on writing a lot of java centric logic. Use DOM when you want to delegate to a different binding solution (say JAXB rather than using JAXB types) or you want to only use standard XML tools on the data types.

For example your method signature could be



   Foo echo(Foo complexObj);



   DOM echo (DOM complexXML);

Don Box has made the point that probably web service engines like Indigo should be in the business of routing, reliability and security and be out of the business of data binding. At first I thought this was wrong but then I realized it was a really nice factoring of the plumbing with the data types. Let the WebService engines deal with the messages and then delegate the type resolution and binding to a later stage.

What's new in the next version of WebLogic WebServices?

An interview I did for dev2dev.