How to Migrate to API Version 4
Migrating your code form Legacy version 3 of the API to version 4 is easy once you understand the conceptual differences between version 3 and 4. The main conceptual difference between Legacy version 3 and version 4 is that version 4 is a stateless SOAP API. That means that the majority of all calls have REST-style statelessness. For a less abstract explanation, let's take a look at version 4 in terms of noun/verb comparison. Consider objects (accounts, deliveries, contact, etc.) to be nouns. Think of functions (add, update, delete, read) as verbs. Using this comparison, we can take an object and apply an action verb to it (add, update, delete, read) depending on what you want to do with the object. Everything you need to perform an action (i.e. a function call) on an object is included in the function call on the client side. For function calls where data is being written or deleted (add, update, delete), the object attributes are the same for each object. In other words, there are common set of object attributes required to interact with a given object when performing a write or delete. For function calls where data is being read, the parameters for each function are unique to the object being read, however, the filterOperators are common across all read functions.
API Tokens
You no longer need a username, password, and sitename to login. Before logging into an account using version 4, the account must have the API feature enabled, and must have at least one API token created. API tokens act as an authentication and control object, and are similar to users. API tokens can have any combination of read, write, and sending permissions, and can be activated, deactivated, or deleted at any time. API tokens can be created programmatically via the API, or interactively in the application.
pageNumber - vs - readNext
The readNext function has been removed in version 4. Keeping with the theme of statelessness, pageNumber is included as a parameter in read functions. pageNumber retrieves the next "batch" of objects as the value specified increases from 1. To obtain an entire set of objects for a given call, you can increase the number value assigned to pageNumber until no more objects are returned.
Add/Update - vs - Write
In version 4, we have broken the Write function into separate Add and Update functions. In other words, there are now two functions which perform a "write", add and update.
Enhanced Filtering
Filtering capabilities have been improved in version 4 to allow for enhanced filtering of strings and dates. For a detailed explanation of the available filters, see filterOperator
Header/Footer and Segment Objects
The header/footer and segment objects have been added in version 4. The header/footer object supports each of the four function calls (add, update, delete, and read). At present, the segment object only supports the read function. We will be providing support for additional add, update and delete functions for segments in the near future.
