Implementation Considerations

Before you build an integration application or other client application, consider the data management, use limits, and communication issues explained in this section.

Choosing a User for an Integration

When your client application connects to the API, it must first log in. You must specify a user to log in to Salesforce when calling login(). Client applications run with the permissions and sharing of the logged-in user. The following sections include information that help you to decide how to configure a user for your client application.

Permissions

An organization's Salesforce administrator controls the availability of various features and views by configuring profiles and permission sets, and assigning users to them. To access the API (to issue calls and receive the call results), a user must be granted the “API Enabled” permission. Client applications can query or update only those objects and fields to which they have access via the permissions of the logged-in user.

If the client application logs in as a user who has access to data via a sharing rule, then the API must issue an extra query to check access. To avoid this, log in as a user with the “Modify All Data” permission. This can speed up the call response time. If providing the “Modify All Data” permission is too permissive for a particular user, consider using the “Modify All” object-level permission to restrict data access on an object basis. For more information on permissions, see Factors that Affect Data Access.

Limits

There is a limit on the number of queries that a user can execute concurrently. A user can have up to 10 query cursors open at a time. If 10 QueryLocator cursors are open when a client application, logged in as the same user, attempts to open a new one, then the oldest of the 10 cursors is released. If the client application attempts to open the released query cursor, an error results.

Multiple client applications can log in using the same username argument. However, this increases your risk of getting errors due to query limits.

If multiple client applications are logged in using the same user, they all share the same session. If one of the client applications calls logout(), it invalidates the session for all the client applications. Using a different user for each client application makes it easier to avoid these limits.

Note
In addition to user limits, there are limits for API requests for each organization. For more information, see API Usage Metering.

Login Server URL

The SOAP implementation of the API also provides a single login server. You can log in to any organization via a single entry point, without having to hard-code the instance for your organization. To access an organization via the API, you must first authenticate the session by sending a login() request to the login server at one of the following URLs, depending on your choice of WSDL.

The less secure version of each URL is also supported.

http://login.salesforce.com/services/Soap/c/31.0

The less secure version of the URL is supported, but not recommended. It is helpful for debugging through proxy servers.

All subsequent calls to the server during the session should be made to the URL returned in the login() response, which points to the server instance for your organization.

Log in to the Login Server

Before invoking any other calls, a client application must first invoke the login() call to establish a session with the login 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 Step 4: Walk Through the Sample Code.

Salesforce checks the IP address from which the client application is logging in, and blocks logins from unknown IP addresses. For a blocked login via the API, Salesforce returns a login fault. Then, the user must add their security token to the end of their password in order to log in. A security token is an automatically-generated key from Salesforce. For example, if a user's password is mypassword, and their security token is XXXXXXXXXX, then the user must enter mypasswordXXXXXXXXXX to log in. Users can obtain their security token by changing their password or resetting their security token via the Salesforce user interface. When a user changes their password or resets their security token, Salesforce sends a new security token to the email address on the user's Salesforce record. The security token is valid until a user resets their security token, changes their password, or has their password reset. When the security token is invalid, the user must repeat the login process to log in. To avoid this, the administrator can make sure the client's IP address is added to the organization's list of trusted IP addresses. For more information, see Security Token.

Once you are logged in, you can issue API calls. For each operation, client applications submit a synchronous request to the API, await the response, and process the results. The API commits any changed data automatically.

API calls:

Typical API Call Sequence

For each call, your client application typically:

  1. Prepares the request by defining request parameters, if applicable.
  2. Invokes the call, which passes the request with its parameters to the Force.com Web Service for processing.
  3. Receives the response from the API.
  4. Handles the response, either by processing the returned data (for a successful invocation) or by handling the error (for a failed invocation).

Salesforce Sandbox

Enterprise, Unlimited, and Performance Edition customers have access to the Salesforce Sandbox, which is a testing environment that offers a full or partial copy of your organization's live production data. For more information about Salesforce Sandbox, please visit the Salesforce.com Community website at www.salesforce.com/community or see “Sandbox Overview” in the Salesforce online help.

To access your organization's Salesforce Sandbox via the API, use the following URLs to make login requests.

Multiple Instances of Salesforce.com Database Servers

Salesforce.com provides many database server instances. Although organizations are generally allocated by geographic regions, an organization may be on any instance.

Content Type Requirement

In the API version 7.0 and later, all requests must contain a correct content type HTTP header, for example: Content-Type: text/xml; charset=utf-8. Earlier versions of the API do not enforce this requirement.

Monitoring API Traffic

You can monitor the number of API requests generated by your organization in two ways.

API Usage Metering

To maintain optimum performance and ensure that the Force.com API is available to all of our customers, salesforce.com balances transaction loads by imposing two types of limits:

When a call exceeds a request limit, an error is returned.

Concurrent API Request Limits

The following table lists the limits for various types of organizations for concurrent requests (calls) with a duration of 20 seconds or longer:

Organization Type Limit
Developer Edition 5
Trial organizations 5
Production organizations 25
Sandbox 25

Total API Request Limits

The following table lists the limits for the total API requests (calls) per 24-hour period for an organization.

Salesforce Edition API Calls Per License Type Minimum Maximum
All Editions: DebuggingHeader on API testing calls for Apex specified. Valid in API version 20 and later. N/A 1,000 1,000
Developer Edition N/A 15,000 15,000
  • Enterprise Edition
  • Professional Edition with API access enabled
  • Salesforce: 1,000
  • Force.com App Subscription: 200
  • Salesforce Platform: 1,000
    Note
    This license is not available to new customers.
  • Force.com - One App: 200
    Note
    This license is not available to new customers.
  • Partner Community: 200
  • Gold Partner: 200
    Note
    This license is not available to new customers.
5,000 1,000,000
  • Unlimited Edition
  • Performance Edition
  • Salesforce: 5,000
  • Force.com App Subscription: 200
  • Salesforce Platform: 5,000
    Note
    This license is not available to new customers.
  • Force.com - One App: 200
    Note
    This license is not available to new customers.
  • Partner Community: 200
  • Gold Partner: 200
    Note
    This license is not available to new customers.
5,000 Unlimited. However, at any high limit, it is likely that other limiting factors such as system load may prevent you from using your entire allocation of calls in a 24–hour period.
Sandbox N/A N/A 5,000,000

Limits are enforced against the aggregate of all API calls made by the organization in a 24 hour period; limits are not on a per-user basis. When an organization exceeds a limit, all users in the organization may be temporarily blocked from making additional calls. Calls will be blocked until usage for the preceding 24 hours drops below the limit.

Note
Limits are automatically enforced for all editions.

Any action that sends a call to the API counts toward usage limits, except the following:

  • Outbound messages
  • Apex callouts

You can create an API usage metering notification, so that Salesforce will send an email to a designated user when API limits have exceeded a specified limit in a specified time period. For more information, see “About API Usage Notifications” in the Salesforce online help.

There are also limits on the number of requests allowed per organization from the Salesforce user interface. For details, see “Concurrent Usage Limits” in the Salesforce online help.

Example API Usage Metering Calculations

The following examples illustrate API usage metering calculations for several scenarios:
  • For an Enterprise Edition organization with five Salesforce licenses, the request limit is 5,000 requests (5 licenses X 1,000 calls).
  • For an Enterprise Edition organization with 15,000 Salesforce licenses, the request limit is 1,000,000 (the number of licenses X 1,000 calls is greater than the maximum value, so the lower limit of 1,000,000 is used).
  • For a Developer Edition organization that made 4,500 calls at 5:00 AM Wednesday, 499 calls at 11:00 PM Wednesday, only one more call could successfully be made until 5:00 AM Thursday.
  • For an Enterprise Edition organization with 20 Gold Partner licenses, the request limit is 5,000 (the number of licenses X 200 calls is less than the minimum value of 5,000).

Increasing Total API Request Limit

The calculation of the API request limit based on user licenses is designed to allow sufficient capacity for your organization based on your number of users. If you need a higher limit and you don't want to purchase additional user licenses or upgrade to Performance Edition, you can purchase additional API calls. For more information, contact your account representative.

Before you purchase additional API calls, you should perform a due diligence of your current API usage. Client applications, whether it is your own enterprise applications or partner applications, that make calls to the API can often be optimized to use fewer API calls to do the same work. If you are using a partner product, you should consult with the vendor to verify that the product is making optimal use of the API. A product that makes inefficient use of the API will incur unnecessary cost for your organization.

Compression

The API allows the use of compression on the request and the response, using the standards defined by the HTTP 1.1 specification. This is automatically supported by some SOAP/WSDL clients, and can be manually added to others. Visit https://developer.salesforce.com/page/Tools for more information on particular clients.

Compression is not used unless the client specifically indicates that it supports compression. For better performance, we suggest that clients accept and support compression as defined by the HTTP 1.1 specification.

To indicate that the client supports compression, you should include the HTTP header “Accept-Encoding: gzip, deflate” or a similar heading. The API compresses the response if the client properly specifies this header. The response includes the header “Content-Encoding: deflate” or “Content-Encoding: gzip,” as appropriate. You can also compress any request by including a “Content-Encoding: deflate” or “gzip” header.

Most clients are partially constrained by their network connection, even on a corporate LAN. The API allows the use of compression to improve performance. Almost all clients can benefit from response compression, and many clients may benefit from compression of requests as well. The API supports deflate and gzip compression according the HTTP 1.1 specification.

Response Compression

The API can optionally compress responses. Responses are compressed only if the client sends an Accept-Encoding header with either gzip or deflate compression specified. The API is not required to compress the response even if you have specified Accept-Encoding, but it normally does. If the API compresses the response, it also specifies a Content-Encoding header with the name of the compression algorithm used, either gzip or deflate.

Request Compression

Clients can also compress requests. The API decompresses any requests before processing. The client must send up a Content-Encoding HTTP header with the name of the appropriate compression algorithm. For more information, see:

Note
To implement request SOAP compression in a Java client with WSC (Web Service Connector), call setCompression() on the Config you use to instantiate a Connection object with. For an example, see login() sample code.

HTTP Persistent Connections

Most clients achieve better performance if they use HTTP 1.1 persistent connection to reuse the socket connection for multiple requests. Persistent connections are normally handled by your SOAP/WSDL client automatically. For more details, see the HTTP 1.1 specification at:

http://www.w3.org/Protocols/rfc2616/rfc2616-sec8.html#sec8.1

HTTP Chunking

Clients that use HTTP 1.1 may receive chunked responses. Chunking is normally handled by your SOAP/WSDL client automatically.

Internationalization and Character Sets

The API supports either full Unicode characters or ISO-8859-1 characters. The character set for your organization depends on the Salesforce instance your organization uses. If your organization logs into ssl.salesforce.com, then your encoding is ISO-8859-1. All other instances use UTF-8. You can determine the character set for your organization by calling describeGlobal() and inspecting the encoding value returned in the DescribeGlobalResult.

If your organization uses ISO-8859-1 encoding, then all data sent to the API must be encoded in ISO-8859-1. Characters outside the valid ISO-8859-1 range might be truncated or cause an error.

Note
The API response is encoded in the character set used by your organization (UTF-8 or ISO-8859-1). Either way, the encoded data is usually handled for you by the SOAP client.

XML Compliance

The API is based on XML, which requires all documents to be well formed. Part of that requirement is that certain Unicode characters are not allowed in an XML document, even in an escaped form, and that others must be encoded according to their location. Normally this is handled for you by any standard SOAP or XML client. Clients must be able to parse any normal XML escape sequence, and must not pass up invalid XML characters.

Some characters, as mentioned, are illegal even if they are escaped. The illegal characters include the Unicode surrogate blocks and a few other Unicode characters. All are seldom-used control characters that are usually not important in any data, and tend to cause problems with many programs. Although they are not allowed in XML documents, they are allowed in HTML documents and may be present in Salesforce data. The illegal characters will be stripped from any API response.

Illegal characters:

For UTF-8 encoding, Salesforce supports only the basic UCS-2 encoding (two byte, Basic Multilingual Plane), and does not support any of the extended UCS-4 characters. UCS-4 support is extremely rare in any system. UCS-2 is the encoding that Java and Windows support. For more information about XML characters and character sets, see: http://www.w3.org/TR/REC-xml#charsets.

.NET, Non-String Fields, and the Enterprise WSDL

If you use .NET with the enterprise WSDL, .NET will generate an extra Boolean field for each non-string field. For example, if you had a date value in MyField__c, .NET generates a Boolean field for each. In this example, the generated fields would be MyField__cSpecified and LastModifiedSpecified. These field values are false by default. If a Specified field value is false, then the values in the corresponding original field will not be included in the SOAP message.

For example, before the values in the currency field annualRevenue can be included in a SOAP message generated by your client application, the value of annualRevenueSpecified must be set to true.

account.annualRevenue = 10000;
account.annualRevenueSpecified = true;
© Copyright 2000–2014 salesforce.com, inc. All rights reserved.
Various trademarks held by their respective owners.