Best Practices
Table Of Contents
- Duplicated Request
- Response Error Handling
- Getting API Support
Duplicated Requests
Continuously sending the same request data over time will result in a timed-ban. The API server has spam detection implemented whereby if the same request data is received continuously, the account will be flagged for a ban/timeout.
For example, if a user has a bad script that calls the EditContactsRequest API on all the contacts from their end that only requires an update for a contact (contact #5678 in the example below):
<EditContactsRequest>
<Contacts>
<Contact contact_id="1234" request_id="a1b2c3">
<Firstname>Update Is</Firstname>
<Lastname>Not Required</Lastname>
...
</Contact>
<Contact email="5678" request_id="d4e5f6">
<Firstname>Update Is</Firstname>
<Lastname>Required</Lastname>
...
</Contact>
...
</Contacts>
</EditContactsRequest>
This would trigger an update not only for contact #5678 but for contact #1234 as well from the API server. This causes the 'Permission Path and Updates' section in the Attribution tab for contact #1234 to be flooded with unnecessary logs in the web app.
API users are encouraged to audit their script to only send the delta changes to prevent flooding their own account with unnecessary data.
For example, the best practice is to send:
<EditContactsRequest>
<Contacts>
<Contact email="5678" request_id="d4e5f6">
<Firstname>Update Is</Firstname>
<Lastname>Required</Lastname>
...
</Contact>
</Contacts>
</EditContactsRequest>
Response Error Handling
It is considered best practice for the API users to have some sort of response error handling in place in the script that requests the API.
The API server always contains the <Result> tag in the response. The server will return <Result>Success</Result> if the request is received and processed successfully. Otherwise, the value will be 'Error'.
A script should roughly have a logic flow like so:
Script start
// Generate the API request arguments
postData = {
account_id: 12345
...
}
// HTTP Post to API request with the request arguments
response = POST(apiUrl, <GetContactsRequest>, postData);
// Parse the reponse
if (response) {
xml = decode XML from response
if (xml <Result> is NOT 'Success') {
$errorCode = get the error code from <ErrorCode>
$errorMessage = get the error message from <ErrorText>
} else if (xml <Result> is 'Success') {
process the xml
}
}
Getting API Support
In order to make it easier to assist with API report/inquiries, it is considered best practice to:
- Provide description of the matter as detailed as possible
- Show the steps to replicate the issue
- Provide the API request samples in CURL format
- Provide the API response data
Example of API request in CURL format
curl -X POST \
-d "email=me@example.com" \
-d "auth_token=[redacted]" \
-d "xml=<GetContactsRequest group_id="9985"></GetContactsRequest>" \
https://api.stgi.net/api-xml
Example of API response data
<AddContactsResponse>
<Contacts>
<Contact>
<Result>Error</Result>
<ErrorCode>1404</ErrorCode>
<ErrorCode>Invalid account_id</ErrorCode>
</Contact>
</Contacts>
</AddContactsResponse>