Improving client app performance
The REST and SOAP API Guides provide information about how Responsys processes the API calls. This section provides additional tips for improving client application performance:
Managing sessions
For the REST API: There are no "sessions" when using the REST API. For the REST API, a valid login request results in an authentication token, which you must send in the header of subsequent REST API requests. The authentication token expires after two hours unless you use the “Refresh Token” request. Refresh Token sends you a new token to use. You do not need to log out when using the REST API.
For the SOAP API:
- For SOAP sessions, a valid login call results in a session ID and a cookie. Your API code must pass the session ID in subsequent calls. The client application maintains the state using the cookie.
- SOAP session tokens expire automatically after two hours of inactivity. Client applications that make infrequent login calls should make explicit logout calls, so that the session limit is not exceeded.
- Responsys allows each account to have a maximum of 100 concurrent SOAP API sessions. If this limit is exceeded, the system returns an "API Limit Exceeded" error message.
- We do not support caching credentials or sharing a single HTTP session (JSESSIONID) between multiple application nodes. SOAP is “sticky” to the session. Attempting to share sessions between multiple threads invalidates the JSESSIONID of another. If you attempt to share a single session between multiple application nodes, you will receive an INVALID_SESSION_ID error.
- Use a separate QA and Production API user. When your QA and Production servers run concurrently while using the same API user, this can cause runaway processes that don’t turn off and it cuts the usable capacity in half.
- We recommend logging in and logging out in an even number of pairs. This helps the system match the persistent sessions and cookies.
- Log out when your session is completed. This prevents you from running out of sessions, which is particularly important when performing transactional processing.
Managing API volume
Because the API clients share the Responsys environment, Responsys monitors and throttles the frequency of API requests that are submitted from each Oracle Responsys account.
To manage API volume:
- Use the throttling API to determine your account's throttling limits. For details, see Throttling.
-
When developing your client application, make the number of calls to process per minute a configurable value (for example, use an external configuration file). If your account’s throttling limit changes, you can adjust the configuration quickly. For example, if your throttling limit in the configuration file is set to 200, and Responsys changes it to 500, then you only have to make the change in one place.
Note: Increasing your throttling limit will not process requests faster. A larger throttling limit increases the amount of requests allowed per minute to the API.
- Use batching for our API calls that merge list recipients and that trigger campaigns.
- You can batch up to 200 recipients per request.
- Using batching greatly increases the number of recipients that you can process per minute. For example, if you have a promotional email campaign that you want to send through the API, you could make up to 500 trigger email message requests per minute with each request containing 200 recipients, for a total of 100,000 email messages sent per minute.
- Using these API calls in a transactional way (that is, one recipient per call) limits the volume you can process to 500 recipients per minute.
- When making an API call in your client application, we recommend setting a timeout for the maximum expected duration of the API call. You may need to test and adjust so that you find the balance between avoiding queuing problems (too small of a timeout) and allowing too much time (too large of a timeout).
- For promotional calls with the maximum number of recipients included, start with two minutes and adjust from there
- For transactional (1:1) calls, you will be limited to 500 recipients per minute. Start with a very small timeout, such as a half or a quarter of a second. Due to network latency and server load, you may need to set the timeout to 10 minutes or longer.
- In the event of a timeout, your client application should reattempt to connect. The Responsys API allows up to 5 retries.
- Watch for error codes related to throttling:
- When an account exceeds its allowable frequency rate limit for an API request, you see the error code API_LIMIT_EXCEEDED and the message “You exceeded your allowable limit to call the <function_name> API function. Please try again in a minute.”
- If a specific user of an account is blocked from using selected API functions, the user sees the error code API_BLOCKED with this message: “The <function_name> is currently not available to this user. Please contact tech support.”
Designing for client-side queuing
Oracle Responsys is a synchronous processing server. It does not queue API calls.
- We recommend that you maintain a commercial queuing system and logically retry failed calls. However, take into account the error type when determining whether to retry. For example, connection reset errors are good candidates for a retry. Bad formatting or "campaign not found" errors point to issues that require something be addressed before retrying the request.
- The Responsys API allows up to five retries.