Main Content | Comments | Subcribe via RSS

Preview: Your Members API

September 8th, 2009 Posted in Featured

Since we have started discussing this on the forums I thought it was time to introduce one of the most powerful new features of Your Members 1.5.x stream coming in 1.5.4 the external API.

This is a preview some features are subject to change

Your Member already has hooks and actions

People maybe confused as Your Members already has an API or rather an internal extension of the Wordpress hooks and Filters with over 20 ways to hook into and interact with Your Member and 100’s of others within Wordpress but these are only accessible within Wordpress framework meaning you need to create a Wordpress plugin to act as a bridge. We show an example of doing this and using actions and filters here.

What the Your Members API does is allow limited ability to call YM and wordpress functions outside of Wordpress and indeed outside of the Domain using a REST based API.

Your Members API vs Actions

So why use the API lets take a look at a traditional problem, integrating an autoresponder, right now adding Aweber or similar support can be done with actions, once a user has completed the YM registration a second plugin calls the ym_return_xxx where xx is the gateway being used to pull the userdata from YM and send it to the autoresponder which in turns confirms the user email, this forces the user to interact with the process several times, likewise Your Members has no way of knowing if the process was a success and likewise the autoresponder can’t tell if the user is still a member.
Traditional Action Approach

  1. User Initiates contact with Your Members
  2. Your Members sends email to user, and request to Autoresponder
  3. Autoresponder sends email to user
  4. User confirms email to autoresponder

With an api the autoresponder can trigger the events and while the number of steps remain the same the interaction with the user is reduced.
Your Members API

  1. User Initiates contact with Autoresponder
  2. User confirms email to Autoresponder
  3. Autoresponder sends API request to Your Members
  4. Your Members sends info to users

For a second example say you are selling a digital or physical product a DVD as well as offering a 6 month option to your site, the choices for integration up until now have been to send them an email with a coupon for your offer, with the API the shopping cart system can instantly assign them membership access to the site. This would be the perfect tool for trusted Joint Venture projects or internal cross selling.

The API doesn’t just add users it can also pool users for information, providing a service to a dedicated account type simply call the useris method likewise if you want to check they have access to a certain post (for example if you are streaming VOD you can protect the video) using the API.

Your Members API calls

Calls are structured as domain.com/YMpath/?ymapi&action=[method]&key=[securitykey] with Private key being sent in post as private=[privatekey] additional method parameters can be sent POST or GET (note for security reasons we might restrict this to POST or at least add the option) the return is simple XML.

Example Your Members API call

http://www.example.com?ymapi&acton=add&key=timbo1 POST private=346734hbbgg374837gd email=test@example.com sub_id=5_y_basic

Returns:

< ?xml version="1.0" encoding="utf-8" ? >
< rsp stat="ok">
< method>add< /method>
< user_id>3< /user_id>
< ustamp>125240612< /ustamp>
< /rsp>

or if there is a problem

< ?xml version="1.0" encoding="utf-8" ?>
< rsp stat="fail">
< err code="[error-code]" msg="[error-message]" />
< /rsp>

If this seems familiar its because its the same method as Flickr, Twitter and many other services offer.

Your Members API Methods

The following calls can be made each can be made via POST/GET and all subject to change in particular delete which we are still pondering including.

Method Add User [add]

Provides the ability to add users and assign a default subscription, Purchased Post or Purchased Post Pack

Parameters:

  • Email – Users email address Required
  • name – Users first name, if not present Email will be used for login
  • sub_id – Subscription ID for subscription to be assigned
  • post_id – Post ID for associating paid post
  • pack_id – PackID for associating paid post packs

Returns:

  • user_id – Wordpress generated userID number

Method Cancel User [cancel]

Switches subscription of user to inactive but does not delete user account
Parameters:

  • Email – Users email address
  • userid- Users ID

Returns:

  • true – boolean true false

Method delete User [delete] – NOT CONFIRMED

Deletes the user account
Parameters:

  • Email – Users email address
  • userid- Users ID

Returns:

  • true – boolean true false

Method User Is Account Type [useris]

Returns the current account and subscription information of the user
Parameters:

  • Email – Users email address
  • userid- Users ID

Returns:

  • userid – Wordpress User ID
  • account_type – users current Your Members Account type
  • sub_id – The current subscription they are on
  • active – boolean true|false

Method User has access to post/page [userhasaccess]

Check userid and post_id against the user_has_access() function
Parameters:

  • post_id – Post ID to check against Required
  • Email – Users email address
  • userid- Users ID

Returns:

  • true – boolean true false

Your Members API Security

The biggest issue with the API is security and as such it will be shipped switched off! This tool is designed for people who know what they are doing and want to really integrate their membership site with other services or third parties such as Joint Ventures. Every API call must be made with a valid Private key (a user can have multiple private keys) and a 6 digit security key. Both sets of keys can be tied down further (unfinished) restricting to specific referrer for example. Finally every API call is logged and can be exported to csv.

Leave a Reply