You may find yourself in a situation where you want to interact with the WishList Member API from a non-PHP application. Some good examples include an iOS or Android application or via JavaScript, .NET, or some other language.
In this case, you won't be able to use any of our PHP wrappers and will need to interact with the REST API directly.
One of the biggest problems we've seen developers get caught up on when interacting with the WishList Member REST API directly is authentication. The API uses a 4-part handshake to authenticate requests so it's a bit more involved them simply posting your API key.
Here's what happens on a typical request:
You generate a request from your site/app to the API to the /auth resource. The first thing auth does is to check if an element named “key” was posted in the $_POST data and if the value of that key = what it calculates the hash should be.
The hash it calculates is based of off the “lock” it is working from (more on that later) and the API key it pulls from WLM. In PHP, it's $auth_key = md5($lock . $api_key); If $_POST[‘key'] equals $auth_key the auth does a couple things:
- First, it sets an auth cookie. The name of that cookie is md5(‘WLMAPI2' . $auth_key). The value of that cookie is $auth_key;
- Then, it returns a response array in the format $response = array(‘success'=>1, ‘key'=>$auth_key);
On the client side, CURL returns the response and saves the cookie. It does this in a cookie file. In wlmapiclass.php, you'll see the options curl_setopt($ch, CURLOPT_COOKIEFILE, $cookie_file) and curl_setopt($ch, CURLOPT_COOKIEJAR, $cookie_file).
COOKIEFILE tells the server which file to READ cookies from and COOKIEJAR tells the server where to save cookies. In this instance, that's the same file. Of course, that's really just how CURL handles cookies. The key piece is the “lock” cookie, because…
If $_POST[‘key'] does NOT exist or equal $auth_key, the the API does the following:
- Set a “lock” cookie. The name of the cookie is “lock” and the value is a time-bashed hash generated by the API.
- Then, it returns a response array in the format $response = array(‘success'=>1, ‘lock'=>$lock);
- That lock then becomes the basis for authentication.
The big key here is the lock cookie. The cookie that gets set by the API is session based. So, it only expires when the browser is closed.
In the above, the hash that is generated is based of off the lock cookie. The API first checks to see if a lock cookie exists: $lock = $_COOKIE[‘lock'];
If it does, that lock is what's used to generate the $auth_key hash and authenticate subsuquent requests. If $_COOKIE[‘lock'] doesn't exist then the API generates a new one and returns it as described above.
So, you need a way in your application to set a cookie that the API can read. In CURL, it's done by creating a cookie file and using COOKIEFILE and COOKIEJAR to read/write that cookie file.
In jQuery, it's just creating a browser cookie with the proper name and value which is this trivial:
$.cookie("lock", this.lock);
With this.lock being the value returned from the API in its response. That's how the authentication “lives” across requests. It's based on the value of “lock” stored in a cookie.
If you're getting “Not Authenticated” error messages this is why.
