MailChimp API v1.3.0 (finally) released

[jesse]

tl;dr - the gorry details are in the changelog and many of these items
were covered in the Issue Tracker:
http://www.mailchimp.com/api/changelog.php
http://code.google.com/p/mailchimp-api/issues/list


Looking back, it's been 4 months since our last v1.2.7 point release
and a bit over a year and half since the original v1.2.0 release -
wow, time flies. That time has given us a lot of time to make A LOT of
changes to our new iteration of the API, and there are definitely some
major ones. So - we're sorry in advance that the upgrade path isn't
more clean, but we hope folks will appreciate the need for the
additions/changes.

There are 6 general areas where work was done:
* JSON Input Parameters
* Campaign content and Template editing/management
* Proper paging support (in methods that support it)
* General Data Management - folders, ecomm360, templates
* New/modified List & Campaign data methods
* Name standardization, renamed methods, and documentation


JSON Input Parameters
==========================================================
This may be the most exciting change we've made in quite a while since
it really changes the ease with which people can start using the API
and/or simplify existing code/wrappers. Essentially up until now,
there were two methods for sending Input Parameters (method arguments)
- XML-RPC or Serialized URL parameters. While both are fairly well
known, array/struct formatting always seemed to confuse people.

Now? Now you can shove your parameters into a JSON object, do an HTTP
POST to the proper url (you just need a GET "output" parameter), and
we'll handle it as you'd expect. While nothing else changed, the
"Connection Overview" page was rewritten to hopefully be more clear
(feedback welcome!):
http://www.mailchimp.com/api/rtfm/

We don't have a ton of examples built yet, but you can see a PHP
example in the 2nd listSubscribe() example code:
http://www.mailchimp.com/api/1.3/listsubscribe.func.php

Please note that JSON Input Parameter support is only available with
v1.3 of the API and later.

To get an idea of how this simplifies things - especially in this case
using Ruby's method_missing functionality, take a look at the Gibbon
gem written by one of our mobile developers:
https://github.com/amro/gibbon

That's 46 lines of code that supports the entire v1.3 of the API and
will continue to even if we change/add parameters or method names.


Campaign content and Template editing/management
==========================================================
* campaignTemplates() was changed to templates() and works slightly
differently

Ever since we released our Template Language, people have clamored for
the ability to more easily access a Campaign's editable regions based
on the names in the template sections. Before it was a painful HTML
parsing process and probably not worth messing with.

Now? Now we've added the campaignTemplateContent() method which very
clearly returns the editable sections along with the current content
in them. Those can fairly simply then be passed back in using
campaignUpdate().

But, we didn't stop there. User templates have always been exposed if
you, say, wanted to create a mini-gallery for a user to select from.
Now, though, we have exposed our full in-app Template Gallery as well
as our Base Start From Scratch templates - as with User templates,
you'll get a name and preview image (they are much more reliable now
due to unrelated backend changes) and some other useful meta data.
Since the Gallery style listing can already be a good bit of data and
we didn't want to slow it down, some more details data has been pushed
into a templateInfo() method which will return editable sections,
default content, and full content preview (think our preview pane).

Then we realized that it was silly to not just allow full management
of User templates. To that end, these new methods are available:

templateAdd(), templateUpdate() , templateDel(), templateUndel()

It should be very obvious what they do. If not, go play around in our
Template Editor (not editing a campaign) and revisit them.


Proper Paging Support
==========================================================
The main gripe here was that even though we allowed paging, getting a
total for proper UI controls was a pain or simply impossible. dur.
This was easy enough to change, but it does mean that a spattering of
methods now return data completely different than they did in 1.2 and
prior. They are:

campaigns(), campaignAbuseReports(), campaignBounceMessages(),
campaignEcommOrders(),
campaignOpenedAIM(), campaignNotOpenedAIM(),
campaignClickDetailAIM(), campaignEmailStatsAIMAll(),
lists(), listMembers(), listAbuseReports(), ecommOrders(),


New/modified List & Campaign data methods
==========================================================
Lots of data exposed in our app that was not accessible has been
added.

* lists() now supports filter parameters like campaigns() always has
and has additional stats available.
* listMemberInfo() supports pulling data for 50 emails at a time and
has added geo data, client data, and static segments inclusions.
* listSubscribe() and listUpdateMembers() allow setting a geo-location
for use segmenting and for Timewarp

New List data methods -
listActivity() (daily stats (sub/unsub/bounce, etc)),
listLocations() (summary geo-data),
listClients() (aggregate mobile/desktop email clients)
listMemberActivity() (recent click/open/unsub/etc data for an
email)

New Campaign related data methods -
campaignMembers() (all campaign members by send status),
campaignBounceMessage() (single bounce message),
campaignsForEmail() (all campaigns in the account for an email)


General Data Management - folders, ecomm360, templates
==========================================================
Template management was mentioned above. Basically we did the same
thing for Folders and Ecomm360 data. campaignFolders() was turned into
a generic folders() and there are additionally:

folderAdd() (previously createFolder()), folderUpdate(),
folderDel()

Similarly Ecomm360 data now has:
ecommOrders() to pull all of them as opposed to a specific
campaign
ecommOrderAdd (was ecommAddOrder()),
campaignEcommOrderAdd() (was campaignEcommAddOrder())


Name standardization, renamed methods, and documentation
==========================================================
While we've been called one, we've never claimed that we have a
RESTful API (it's simply not), however there is something to be said
for at least trying to follow some sort of a naming convention.
Unfortunately as we've added things over the years, that's been more
of "1 of 2 or 3 naming conventions" - sigh. The feeling here was that
since we were already breaking the return formats that people were
using, it's not *that* bad to rename a few methods. However, if there
is enough push-back we may consider bringing them back for 1.3 as
being deprecated. So, these methods were renamed:

* campaignEcommAddOrder() is now campaignEcommOrderAdd()

* listAddStaticSegment() is now listStaticSegmentAdd()
* listResetStaticSegment() is now listStaticSegmentReset()
* listDelStaticSegment() is now listStaticSegmentDel()
* listStaticSegmentAddMembers() is now
listStaticSegmentMembersAdd()
* listStaticSegmentDelMembers() is now
listStaticSegmentMembersDel()

* ecommAddOrder() is now ecommOrderAdd()

* campaignFolders() is now folders()
* createFolder() is now folderAdd()

Next, and hopefully you won't notice, but a first pass at generating
better documentation for the larger returned arrays/structures was
made. The second step of that will be a full redesign of the API site
sometime in the next few months.


Finally, again, for all of the the gorry details (they aren't all
here!) see the changelog:
http://www.mailchimp.com/api/changelog.php

Want to request something, report a bug, or see open issues? We have
an Issue/Request Tracker here:
http://code.google.com/p/mailchimp-api/issues/list



jesse