Review these topics to make sure you understand how the API manages data and communication before building your client applications:
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 the following URL:
https://www.salesforce.com/services/Soap/c/14.0
The less secure version of the URL is also supported:
http://www.salesforce.com/services/Soap/c/14.0
The less secure version of the URL is supported 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. For a list of the 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 contact Customer Support.
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:
| Salesforce Edition | Limit |
|---|---|
|
|
|
|
| Unlimited Edition |
|
| Sandbox |
|
Limits are enforced against the aggregate of all API calls made by the organization in a 24 hour period, and not on a per user basis. When an organization exceeds the limit as calculated above, all users in the organization may be temporarily blocked from making additional calls. Calls will be blocked until enough time has passed for the usage from the preceding 24 hours to drop below the limit. At that time, usage is restored to all users.
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 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.apexdevnet.com/index.php/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 I SO-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.
The following characters are illegal:
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 or the standard field LastModifiedDate, .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;