Before you build an integration application or other client application, consider the data management, use limits, and communication issues explained in this section.
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.
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.
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.
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/24.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.
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:
For each call, your client application typically:
Enterprise Edition and Unlimited 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.
Salesforce.com provides many database server instances. Although organizations are generally allocated by geographic regions, an organization may be on any instance.
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.
You can monitor the number of API requests generated by your organization in two ways.
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.
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 |
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 | 5,000 | 5,000 |
| Force.com Free Edition |
|
5,000 | 1,000,000 |
|
5,000 | 1,000,000 | |
| Unlimited Edition | 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.
Any action that sends a call to the API counts toward usage limits, except the following:
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.
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 Unlimited 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.
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 http://wiki.developerforce.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.
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.
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:
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
Clients that use HTTP 1.1 may receive chunked responses. Chunking is normally handled by your SOAP/WSDL client automatically.
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.
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.
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;