Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Migrate to API v3 #462

Closed
EvanHerman opened this issue Mar 3, 2016 · 4 comments
Closed

Migrate to API v3 #462

EvanHerman opened this issue Mar 3, 2016 · 4 comments

Comments

@EvanHerman
Copy link
Contributor

@EvanHerman EvanHerman commented Mar 3, 2016

Goals:
  • Unbundle the MailChimp API php class wrapper.
  • Create a custom API class wrapper of our own, utilizing WP HTTP classes.
  • Migrate all API calls from v2 to v3 (2.0 to be deprecated 1/1/2017).
Benefits:

Migrating over to the new API will...

  • help with future maintenance/organization.
  • increase code efficiency.
  • bring down the overall plugin file size.

API Migration (v2 => v3 endpoint migrations)

Note: Along with the endpoints changing, the data returned from the MailChimp API may differ. This could be either the formatting of the returned data, or the data entirely (new data adding to the api response or data removed from the response that we were using etc.)

Endpoint Location(s)
/helper/ping admin/class-yikes-inc-easy-mailchimp-extender.php (line 1157)
/lists/unsubscribe admin/class-yikes-inc-easy-mailchimp-extender.php (line 2747)
/lists/list admin/class-yikes-inc-easy-mailchimp-extender.php (line 2850)
admin/partials/ajax/class.ajax.php (line 46)
admin/partials/dashboard-widgets/class.list-activity-widget.php (line 67)
admin/partials/edit-form.php (line 68)
admin/partials/menu/lists.php (line 9)
admin/partials/menu/manage-forms.php (line 19)
admin/partials/menu/manage-lists.php (line 9)
admin/partials/menu/options-sections/integration-settings.php (line 90)
admin/partials/view-list.php (line 7)
admin/partials/view-user.php (line 75)
public/partials/ajax/class.public_ajax.php (line 82)
public/partials/shortcodes/yikes-mailchimp-subscriber-count.php (line 63)
/lists/merge-vars admin/partials/ajax/add_field_to_form.php (line 7)
admin/partials/ajax/process_ajax.php (line 14)
admin/partials/edit-form.php (line 93)
admin/partials/view-list.php (line 29)
admin/partials/view-user.php (line 105)
public/partials/shortcodes/process/process_form_submission_ajax.php (line 207)
public/partials/shortcodes/process/process_form_submission.php (line 212)
/lists/interest-groupings admin/partials/ajax/add_interest_group_to_form.php (line 5)
admin/partials/ajax/class.ajax.php (line 86)
admin/partials/edit-form.php (line 114)
admin/partials/view-list.php (line 52)
/helper/chimp-chatter admin/partials/dashboard-widgets/class.list-activity-widget.php (line 128)
admin/partials/menu/account-details.php (line 58)
/users/profile admin/partials/menu/account-details.php (line 10)
/helper/account-details admin/partials/menu/account-details.php (line 34)
public/partials/ajax/class.public_ajax.php (line 105)
/lists/segments admin/partials/view-list.php (line 79)
/lists/members admin/partials/view-list.php (line 114)
/lists/member-info admin/partials/view-user.php (line 24)
public/classes/checkbox-integrations.php (line 36)
public/classes/checkbox-integrations.php (line 79)
public/partials/ajax/class.public_ajax.php (line 125)
/lists/subscribe public/classes/checkbox-integrations.php (line 172)
public/partials/shortcodes/process/process_form_submission_ajax.php (line 115)
public/partials/shortcodes/process/process_form_submission.php (line 112)
@EvanHerman EvanHerman self-assigned this Mar 3, 2016
@JPry JPry self-assigned this Sep 29, 2016
@TheTracyL TheTracyL added this to the 6.3 milestone Oct 13, 2016
@JPry
Copy link
Collaborator

@JPry JPry commented Oct 24, 2016

API V3 Update

A significant amount of progress was made on the V3 API last week and over the weekend. This message is meant to provide an explanation of the work done so far, as well as the next steps required to complete this task.

Work Completed.

A number of new classes have been created. For organization purposes, they have all been added to the includes/api/ directory. This is the ideal location in the file system to add any additional classes that might be needed on the API.

The classes are as follows:

  • Yikes_Inc_Easy_MailChimp_API - This is the main class that interfaces with the MailChimp API. It has a primary method, send_request(), through which all API data will flow. There are helper methods for each of the HTTP request types that the MailChimp API supports. There are also filters throughout this class to allow other plugins or themes to adjust how the class behaves.
  • Yikes_Inc_Easy_MailChimp_API_Abstract_Items - This is a base class for working with individual endpoints in the API. This class is meant to be extended into a child class for actual use, but contains some useful methods that all children are likely to use. This helps ensure that the code remains DRY (don't repeat yourself).
  • Yikes_Inc_Easy_MailChimp_API_Lists - This is the class that is intended to deal with the /lists endpoint of the API. There are methods in the class that are meant to assist in getting all list-related data from the API. These class methods utilize transients for caching, with the ability for the transients to be used or not in a given request.
  • Yikes_Inc_Easy_MailChimp_API_Account - This is the class for dealing with the MailChimp account as a whole. There is currently only one method, get_account(). It's not likely that this class will need any additional methods.
  • Yikes_Inc_Easy_MailChimp_API_Manager - This is an important class to new API code. It serves as a very simple container for all things related to the API. The only thing you need to provide to this class is the full API key, and from that point on you are able to retrieve instances of the other classes listed above. A helper function has also been created to retrieve this class object: yikes_get_mc_api_manager(). It's worth noting that you should always use the yikes_get_mc_api_manager() function to get this class, and you should then use this class object to always retrieve the other classes listed above that you need to use. Examples of this can be seen throughout the codebase.

Work Remaining

The majority of the old V2 endpoints have been removed from the codebase at this point. There are only a few places where the old V2 endpoints remain:

Endpoint Locations
/lists/subscribe.json public/partials/shortcodes/process_form_submission.php, line 112
public/partials/shortcodes/process_form_submission_ajax.php, line 116
/lists/merge-vars.json public/partials/shortcodes/process_form_submission.php, line 208
public/partials/shortcodes/process_form_submission_ajax.php, line 206

These locations above should be relatively easy to replace using the existing API methods. Utilizing the existing code as an example should help with converting these endpoints.

There are 2 notable files where there are V2 endpoints remaining. However, these are a special situation, as it appears that there are no endpoints in the V3 API comparable to the endpoints used in the V2 API. Or, there may be a comparable endpoint, but the specific data we're using does not seem to exist in the V3 API.

  • /helper/chimp-chatter.json - I have been unable to find anything in the V3 API that seems to be comparable to this endpoint. This endpoint is used here:
    • admin/partials/dashboard-widgets/class.list-activity-widget.php line 113
    • admin/partials/menu/account-details.php line 60
  • /users/profile.json - There is a comparable API endpoint for this data: Yikes_Inc_Easy_MailChimp_API_Lists::get_member(). However, a lot of the specific pieces of data that are being used are not part of this new endpoint. The only usage of this endpoint is on the account details page, admin/partials/menu/account-details.php line 16.
  • /helper/account-details.json - Similar to the above endpoint, there is a comparable endpoint: Yikes_Inc_Easy_MailChimp_API_Account::get_account(). Again, the only usage of this endpoint is for the account details page, admin/partials/menu/account-details.php line 39. Much of the data has been changed or removed. For this specific instance, I was able to incorporate the new API into one of the bits of account data. To fully use the API, we'll have to remove a lot of account data information that is currently displayed, as there won't be a way to retrieve it from the new API.

Next Steps

  • Update the last remaining V2 endpoints with the new V3 methods.
  • Create a V2 API class with a similar model to Yikes_Inc_Easy_MailChimp_API. This could be used to interface with the V2 API in the same manner as the V3 API, for consistency's sake.
  • Add the new class mentioned above to the Yikes_Inc_Easy_MailChimp_API_Manager class.
  • Update the API class to accept an API version
  • Create a Chimp Chatter class, using V2 API
  • Determine what changes should be made to the account details page based on the new API data.
  • Run find/replace to replace all instances of %VERSION% with the next plugin version. This is used primarily in @since tags in docblocks.
@TheTracyL
Copy link
Member

@TheTracyL TheTracyL commented Nov 21, 2016

Evan contacted MailChimp about the missing endpoints and we have an update:

Thanks for writing in to API help at MailChimp. I understand the need for a bit of assistance here, and I'm happy to help out.

Regarding the /helper/chimp-chatter API endpoint, we do not currently have an equivalent endpoint built out for v3.0. That being said, we always want to be attentive to user feedback and if this endpoint disappearing would negatively impact your workflow we would love to hear more. In that case, could you please get back to us with a bit more about your specific workflow and why that call is important for your set up? Then I can pass those details along to our developers to take into consideration. Alternately, our feedback form can be found here, if you'd prefer to use your own words: https://mailchimp.com/contact/feedback/

I have better news about the second endpoint mentioned - the /helper/account-details endpoint is now a GET request to the / endpoint, as detailed here: http://developer.mailchimp.com/documentation/mailchimp/reference/root/#read-get_root

The third endpoint noted, /users/profile also does not yet have an equivalent endpoint in 3.0. As with the previous situation, a bit more detail about your workflow and why that endpoint is necessary will help our developers assess the situation and determine how to best move forward.

Thanks! We really appreciate the email. We look forward to hearing back and helping out as much as we can.
Thank You,
Clair

@TheTracyL
Copy link
Member

@TheTracyL TheTracyL commented Dec 4, 2016

WCUS Meeting Notes

Keep v2 items in that are not being supported in v3 in the API class file.

  • @JPry will work on the class file to include the v2 endpoints
  • @EvanHerman will migrate the few remaining v2 endpoints to v3
  • @kpu23 will update the v2 endpoints for all of the extensions
  • Tracy will test everything after it's done

Affected features not supported by v3:

  • Dashboard widget.

    • ChimpChatter: How many new subscribers, etc.
  • Account details

    • Avatar
    • Company Name
    • Etc Meta Data
@TheTracyL
Copy link
Member

@TheTracyL TheTracyL commented Jan 13, 2017

OMG I'm closing this. 🥇

@TheTracyL TheTracyL closed this Jan 13, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants
You can’t perform that action at this time.