Quick Start

This topic tells you what you need to start using the API in your development environment. It includes the following steps:

Before you begin building client applications, you need to install your development platform according to its product documentation. In addition, you should read Basic Concepts.

Step 1: Obtain a Salesforce Developer Edition Account

If you are not already a member of the Sforce developer community, go to http://www.salesforce.com/developer and follow the instructions for signing up for a Developer Edition account. Even if you already have an Enterprise Edition or Unlimited Edition account, it is strongly recommended that you use Developer Edition for developing, staging, and testing your solutions against sample data to protect your organization's live data. This is especially true for applications that will be inserting, updating, or deleting data (as opposed to simply reading data).

Step 2: Generate or Obtain the Web Service WSDL

To access the AppExchange Web service, you need a Web Service Description Language (WSDL) file. The WSDL file defines the Web service that is available to you. Your development platform uses this WSDL to generate an API to access the AppExchange Web service it defines. You can either obtain the WSDL file from your organization's Salesforce administrator or you can generate it yourself if you have access WSDL download page in the Salesforce user interface. For more information about WSDL, see http://www.w3.org/TR/wsdl.

WSDL Files for Web Services

There are two AppExchange Web services for which you can obtain WSDL files for API access:

AppExchange Enterprise Web services API (enterprise WSDL)-This API is for most enterprise users who are developing client applications for their organization. The enterprise WSDL file is a strongly typed representation of your organization's data. It provides information about your schema, data types, and fields to your development environment, allowing for a tighter integration between it and the AppExchange Web service. This WSDL changes if custom fields or custom objects are added to, renamed, or removed from, your organization's Salesforce configuration.

AppExchange Partner Web services API (Partner WSDL)-This API is for salesforce.com partners who are developing client applications for multiple organizations. As a loosely typed representation of the Salesforce object model, this API can be used to access data within any organization. It is more flexible, although not as easy to use, as its enterprise counterpart. For more information, see Using the Partner WSDL.

Generating the WSDL File for Your Organization

Administrators, and users with the "Modify All Data" permission, can download the Web Services Description Language (WSDL) file to integrate and extend Salesforce using the API. The WSDL file is dynamically generated based on which type of WSDL file (enterprise or partner) you download. The generated WSDL defines all of the API calls, objects (including standard and custom objects), and fields that are available for API access for your organization.

Log in to your Enterprise, Unlimited, or Developer Edition Salesforce account. You must log in as an administrator or as a user who has the "Modify All Data" permission.

Click Setup | Integrate | AppExchange API.

Click the appropriate link to download the enterprise WSDL (if you are a Salesforce customer) or partner WSDL.

Your browser opens the WSDL file.

Save the WSDL file to your local file system.

For the enterprise WSDL file, if new custom fields or objects are added to, renamed, or removed from your organization's information, you need to regenerate the WSDL file in order to access them.

Step 3: Import the WSDL File Into Your Development Platform

Once you have the WSDL file, you need to import it into your development platform so that your development environment can generate the necessary objects for use in building client Web service applications in that environment. This section provides sample instructions for Apache Axis and Microsoft Visual Studio. For instructions about other development platforms, see your platform's product documentation.

The process for importing WSDL files is identical for the enterprise and partner WSDL files.

Instructions for Java Environments (Apache Axis)

Java environments access the API through Java objects that serve as proxies for their server-side counterparts. Before using the API, you must first generate these objects from your organization's WSDL file.

Each SOAP client has its own tool for this process. For Apache Axis, you use the WSDL2Java utility. For more information about using WSDL2Java, see the following URL:

Before you run WSDL2Java, you must have Axis installed on your system and all of its component JAR files must be referenced in your classpath.

java -classpath pathToFirstJAR/FirstJARFilename;pathToSecondJAR/SecondJARFilename 
org.apache.axis.wsdl.WSDL2Java pathToWsdl/WsdlFilename

For AppExchange WSDL files, the -a switch is recommended to configure WSDL2Java. The following sample command uses the -a switch:

java -classpath pathToFirstJAR/FirstJARFilename;pathToSecondJAR/SecondJARFilename 
org.apache.axis.wsdl.WSDL2Java -a pathToWsdl/WsdlFilename

This command will generate a set of folders and Java source code files in the same directory in which it was run. After these files are compiled, they can be included in your Java programs for use in creating client applications.

For most Java development environments, you can use Wizard-based tools for this process instead of the command line. For more information about using WSDL2Java with AppExchange, visit the message boards at http://www.salesforce.com/developer/boards.jsp.

Instructions for Microsoft Visual Studio

Visual Studio languages access the API through objects that serve as proxies for their server-side counterparts. Before using the API, you must first generate these objects from your organization's WSDL file.

Visual Studio provides two approaches for importing your WSDL file and generating an XML Web service client: an IDE-based approach and a command line approach.

Before you begin, the first step is to create a new application or open an existing application in Visual Studio. In addition, you need to have generated the WSDL file, as described in Generating the WSDL File for Your Organization.

An XML Web service client is any component or application that references and uses an XML Web service. This does not necessarily need to be a client-based application. In fact, in many cases, your XML Web service clients might be other Web applications, such as Web Forms or even other XML Web services. When accessing XML Web services in managed code, a proxy class and the .NET Framework handle all of the infrastructure coding.

Add a Web reference to your project for the XML Web service that you want to access. The Web reference creates a proxy class with methods that serve as proxies for each exposed method of the XML Web service.

Add the namespace for the Web reference.

Create an instance of the proxy class and then access the methods of that class as you would the methods of any other class.

On the Project menu, choose Add Web Reference.

In the URL box of the Add Web Reference dialog box, type the URL to obtain the service description of the XML Web service you want to access, such as:

file:///c:\WSDLFiles\enterprise.wsdl

Click the Go button to retrieve information about the XML Web service.

In the Web reference name box, rename the Web reference to sforce, which is the namespace you will use for this Web reference.

Click Add Reference to add a Web reference for the target XML Web service. For more information, see the topic "Adding and Removing Web References" in the Visual Studio documentation.

Visual Studio retrieves the service description and generates a proxy class to interface between your application and the XML Web service.

If you are using Visual Basic .Net and the enterprise WSDL, you will need to modify the generated Web service client to overcome a bug in Visual Studio's client generation utility. The API exposes two objects (Case and Event) whose names conflict with Visual Basic keywords. When the classes that represent these objects are created, Visual Studio wraps the class names with brackets ([Case] and [Event]). This is the method by which you can re-use keywords.

Unfortunately, in the definition of the SObject class, Visual Studio does not wrap these to class references in the System.Xml.Serialization.XmlIncludeAttribute that are part of the SObject definition. To work around this problem in Visual Studio, you need to edit the XmlIncludeAttribute settings for Case and Event as shown below. This does not apply to C# and only applies when using the enterprise version of the WSDL.

     System.Xml.Serialization.XmlIncludeAttribute(GetType([Event])), _ 
     System.Xml.Serialization.XmlIncludeAttribute(GetType([Case])), _

Step 4: Walk Through the Sample Code

Once you have imported your WSDL file, you can begin building client applications that use the API. The fastest way is to learn by example-start by walking through the code example described in Sample Code Walkthrough.