API Call Basics

API calls represent specific operations that your client applications can invoke at runtime to perform tasks, for example:

Using your development environment, you can construct Web service client applications that use standard Web service protocols to programmatically:

See Core Calls, Describe Calls, andUtility Calls for complete details about each call.

Characteristics of API Calls

All API calls are:

  • Service Requests and Responses—Your client application prepares and submits a service request to the Force.com Web Service via the API, the Force.com Web Service processes the request and returns a response, and the client application handles the response.
  • 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 object is committed automatically. This is analogous to the AUTOCOMMMIT setting in SQL. For create(), update(), and delete() calls that attempt to write to multiple records in an object, the write operation for each record 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.
Note
This means that client applications may need to handle some failures: for example, if you create an opportunity that has shipments (a custom object), and the opportunity line item gets created but the shipment creation fails, if your business rules required all opportunities be created with shipment, your client application would need to roll back the opportunity creation.

Factors that Affect Data Access

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

  • Your organization must be enabled for API access, and the user attempting to access the API must have the profile permission "API Enabled" selected. It is selected by default.
  • 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. Via the API, a client application can access objects that are defined in your enterprise WSDL file.
    • 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.

  • Some objects may not appear in the WSDL because you must first contact salesforce.com and request access, for exampleTerritory orCampaign. These objects are noted in the “Usage” section for each object.
  • Whether your configured permissions allow access to the data. Your client application logs in as a user to the Force.com Web Service. The profile associated with the logged-in user grants or denies access to specific objects and fields in your organization.

    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 many objects, including: Account, Asset, Campaign, Case, Contact, Contract, Document, Lead, Opportunity, Pricebook2, Product2, and Solution. Other 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 “Read” on that object can view only those fields that are not hidden on the record. In addition, users with “Read” on an object 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 API respects object-level and field-level security configured in the Salesforce user interface. You can access objects and fields only if the security settings in the logged-in user’s profile permit such access. For example, fields that are not visible to a given user are not returned in a query() or describeSObjects() call. For more information, see Security and the 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. Users are granted the most permissive access that is available to them, either through organization-wide defaults or manual record sharing.
  • Whether your organization uses territory management to control user access to accounts, cases, and opportunities. Territory management is available in Enterprise, Unlimited, and Developer Edition organizations. For more information, see the Salesforce online help.
  • 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 (the value for the object's createable attribute is set to true) in the . To determine what operations are allowed on a given object, your client application can invoke the describeSObjects() call on the object and inspect the following properties in the DescribeSObjectResult: creatable (create() call), updateable (update() call), deletable (delete() call), queryable (query() call), retrievable (retrieve() call), searchable (search() call), and replicatable (getUpdated() and getDeleted() calls).
  • Whether a particular change would compromise the referential integrity of your organization’s Salesforce data. For example:
    • ID values in reference fields (see Reference Field Type ) are validated in create() and update() calls. For information on IDs, see ID Field Type.
    • If a client application delete()s an object instance, then its children are automatically deleted as part of the call if the ChildRelationship’s cascadeDelete property for that child has a value of true. For example, if a client application deletes an Opportunity, then any associated OpportunityLineItem records are also deleted. However, if an OpportunityLineItem is not deletable or is currently being used, then the delete() call on the parent Opportunity will fail. Use DescribeSObjectResult to view the ChildRelationship value if you want to be sure what will be deleted.

      There are certain exceptions which prevent the execution of a cascadeDelete. For example, you cannot delete an account if it has associated cases, if it has related opportunities that are owned by other users, or if associated contacts are enabled for the Self-Service portal. In addition, if you attempt to delete an account that has closed/won opportunities owned by you or has active contracts, then the delete request for that record will fail.

  • Whether a given field in an 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 user interface.
  • Rules for custom objects—such as fields that are configured in the Salesforce user interface to be unique—are not yet enforced via the API, however rules that specify that a field in a custom object is required are enforced. For more information, see Required Fields in Custom Objects.
  • 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 user interface are not accessible or implicitly enforced via the API. For example:
    • Page layouts can specify whether a given field is required, but the 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 page layouts users with different profiles can see. However, such rules that are configured and enforced in the Salesforce user interface are not enforced in the API. For example, the API 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 API 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.

© Copyright 2000-2008 salesforce.com, inc. All rights reserved.
Various trademarks held by their respective owners.