Concepts

The sforce API calls represent specific operations that your client applications can invoke at run-time to perform certain tasks. For example, you can query your organization's data; add, update, and delete information; obtain metadata about your organization's data; and run utilities to perform administration tasks. For detailed information about sforce utility API calls, see sforce Utility API Calls.

Characteristics of sforce API Calls

Service requests and responses-Your client application prepares and submits a service request to the sforce Web service, the sforce Web service processes the request and returns a response, and the client application handles the response as appropriate.

Synchronous-Once the API call is invoked, your client application waits until it receives a response from the service. Asynchronous calls are not supported.

Committed automatically-Every operation that writes to a salesforce.com table is committed automatically. This is analogous to the AUTOCOMMMIT setting in SQL. For create, update, and delete calls that attempt to write to multiple rows in a table, the write operation for each row is treated as a separate transaction. For example, if a client application attempts to create two new accounts, they're created using mutually exclusive insert operations that succeed or fail individually, not as a group.

Factors that Affect Data Access

When using the sforce API, the following factors affect access to your organization's data:

Depending on which WSDL you are using:

Enterprise WSDL: The generated enterprise.wsdl file contains all of the objects that are available to your organization. A client application can access, via the sforce API, objects that are defined in the enterprise.wsdl file that you are using.

Partner WSDL: When using the generated Partner WSDL file, a client application can access objects that are returned in the describeGlobal call.

For more information, see Generating the WSDL File for Your Organization.

Whether your configured permissions allow access to the data. Your client application logs in as a user to the sforce Web service. The permissions profile associated with that logged in user determine the level of access to specific objects and fields in your organization's information.

For certain objects, the user profile is configured with one of the following permissions:

Read-Users can only view objects of this type.

Create-Users can read and create objects of this type.

Edit-Users can read and update objects of this type.

Delete-Users can read, edit, and delete objects of this type.

These permissions apply to the following objects: Account, Asset, Campaign, Case, Contact, Contract. Document. Lead, Opportunity, Pricebook2, and Product2. Other sforce objects (such as AccountTeamMember), follow sharing on the associated permission-assigned object (such as the Account record). Similarly, a Partner depends on the permissions in the associated Account.

User permissions do not affect field-level security or sharing. If field-level security specifies that a field is hidden, users with the "Read" permission can view only those fields that are not hidden on the record. In addition, users with "Read" permissions can view only those records that sharing settings allow. The one exception is the "Edit Read Only Fields" permission, which gives users the ability to edit fields marked as read only via field-level security.

The sforce API respects object-level and field-level security configured in the salesforce.com user interface. You can access objects and fields only if the security settings in the logged-in user's personal profile permit such access. For example, fields that are not visible to a given user are not returned in a query or describeSObject call. For more information, see Security in the sforce API.

Whether the sharing model of the logged-in user allows access to the data. For most API calls, data that is outside of the logged-in user's sharing model is not returned.

Whether a given object is configured to be accessible via certain API calls. For example, to create an object via the create call, its object must be configured as createable (createable=True). To determine what operations are allowed on a given object, your client application can invoke the describeSObject call on the object and inspect the following properties in the DescribeSObjectResult: createable (create call), updateable (update call), deletable (delete call), queryable (query call), retrieveable (retrieve call), searchable (search call), and replicateable (getUpdated and getDeleted calls).

Whether a particular change would compromise the referential integrity of your organization's salesforce.com data. For example:

ID values in reference fields (see Reference Field Type) are validated in create and update calls.

If a client application deletes an object instance, then its children are automatically deleted as well (cascading deletes). For example, if a client application deletes an opportunity, then any associated opportunity line items are also deleted.

A client application cannot delete an object instance if it is referenced by another object instance. For example, a client application cannot delete a particular Account instance if the AccountId field in an Opportunity instance references the ID of that account.

Whether a given field in an sforce object can be updated or not. For example, read-only fields cannot be changed in create or update calls.

Whether a given feature is used by your organization. For example, the RecordTypeId field will appear in your WSDL file only if at least one record type is configured for your organization in the salesforce.com user interface.

Rules for custom objects-such as fields that are configured in the salesforce.com user interface to be required (not null) or unique-are not implicitly enforced via the sforce API.

Ownership changes to one object instance do not automatically cascade to other object instances. For example, if ownership changes for a given Account, ownership does not then automatically change for any Contract associated with that Account-each ownership change must be made separately and explicitly by the client application.

Certain features that are configurable in the salesforce.com user interface are not accessible or implicitly enforced via the sforce API. For example:

Layouts can specify whether a given field is required, but the sforce API does not enforce such layout-specific field restrictions or validations in create and update calls. It is up to the client application to enforce any such constraints, if applicable.

Record types can control which picklist values can be chosen in a given record and which which page layouts users with different profiles can see. However, such rules that are configured and enforced in the salesforce.com user interface are not enforced in the sforce API. For example, the sforce Web service will not validate whether the value in a picklist field is allowed per any record type restrictions associated with the profile of the logged in user. Similarly, the sforce Web service will not prevent a client application from adding data to a particular field simply because that field does not appear in a layout associated with the profile of the logged in user.

If any such constraints are required, it is up to business logic in the client application to enforce them explicitly.

Typical API Call Sequence

Prepares the request by defining request parameters, if applicable

Invokes the call, which passes the request with its parameters to the sforce Web service for processing

Receives the response (synchronously) from the sforce Web service

Handles the response, either by processing the returned data (for a successful invocation) or by handling the error (for a failed invocation).

Start By Logging In to the sforce Server

Before invoking any other sforce API calls, a client application must first invoke the login call to establish a session with the sforce server, set the returned server URL as the target server for subsequent API requests, and set the returned session ID in the SOAP header to provide server authorization for subsequent API requests. For more information, see login and Sample Code Walkthrough.

Concepts

About sforce API Calls

Characteristics of sforce API Calls

Factors that Affect Data Access

Typical API Call Sequence

Start By Logging In to the sforce Server

Core Data Objects