Implementation Considerations

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

SOAP API provides a single login server. You can log in to any org from a single entry point without hard coding the instance. To access an org via the API, 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.

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 org.

Before invoking any other calls, a client app must first invoke the login() call to establish a session with the login server. It then sets the returned server URL as the target server for subsequent API requests and sets the returned session ID in the SOAP header to provide server authorization for subsequent API requests. Salesforce checks the IP address from which the client app is logging in and blocks logins from unknown IP addresses. For more information, see login() and Step 4: Walk Through the Sample Code.

If the API blocks the login, Salesforce returns a login fault. To log in, the user must add the security token at the end of the user’s password. For example, if a user's password is mypassword and the security token is XXXXXXXXXX, the user enters mypasswordXXXXXXXXXX. Users get their security token by changing their password or resetting their security token from the Salesforce user interface. When users change their password or reset 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 the user resets the security token, or changes the password, or you reset the user’s password. When the security token is invalid, the user must repeat the login process. To avoid another log in, add the client's IP address to the org's list of trusted IP addresses.

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

API calls:

• Core Calls
• Describe Calls
• Utility Calls

For each call, your client app typically:

1. Prepares the request by defining request parameters, if applicable.
2. Invokes the call, which passes the request with its parameters to the Lightning Platform 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).

Professional, 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 Salesforce org’s live production data. For more information, visit the Salesforce Community website at www.salesforce.com/community or see Sandbox Types and Templates in the Salesforce Help.

To access your org’s sandbox via the API, use the following URLs to make login requests.

Although orgs are generally allocated by geographic regions, an org may be on any instance.

All requests must contain a correct content type HTTP header, for example: Content-Type: text/xml; charset=utf-8.

To maintain optimum performance and ensure that the Lightning Platform API is available to all our customers, Salesforce balances transaction loads by imposing two types of limits:

• Concurrent API Request Limits
• Total API Request Allocations

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

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 to the HTTP 1.1 specification.

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 depends on the Salesforce instance that your org uses. If your org logs in to ssl.salesforce.com, your encoding is ISO-8859-1. All other instances use UTF-8. To determine the character set, call describeGlobal() and inspect the encoding value returned in DescribeGlobalResult.

If your org uses ISO-8859-1 encoding, 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 unpaired Unicode surrogates 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 are stripped from any API response.

Illegal characters:

• 0xFFFE
• 0xFFFF
• Control characters 0x0 - 0x19, except the following characters, which are legal: 0x9, 0xA, 0xD, tab, newline, and carriage return)
• 0xD800 - 0xDFFF, unless they’re used to form a surrogate pair

If you use .NET with the enterprise WSDL, .NET generates a Boolean field for each non-string field. For example, if you have a date value in MyDateField__c, .NET generates a Boolean field called MyDateField__cSpecified.

The generated field value is false by default. If a Specified field value is false, then the values in the corresponding original field are 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 app, the value of annualRevenueSpecified must be set to true.

1account.annualRevenue = 10000;
2account.annualRevenueSpecified = true;