Best Practices

Table Of Contents

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:

  1. Provide description of the matter as detailed as possible
  2. Show the steps to replicate the issue
  3. Provide the API request samples in CURL format
  4. 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>