API Tutorial – Part III

Welcome to the final part of this tutorial series. In our previous post we have successfully grouped all newly inserted comments into one campaign, send it out and started it via the API. However, what we are still missing is the part where we retrieve the reviews and finally determine if we can publish or decline the comment based on a majority vote as well rating the workers. So let’s get started!

You can try out the completely finished Comment Moderation System at commentmoderation.demo.microwrokers.com. You can also download the end result of this part at commentmoderation.demo.microwrokers.com/Downloads/Step3.zip. We recommend that you download this Zip-File first if you want to follow along as we will only mention the most important steps in this tutorial. A complete documentation of the API can be found here.

Instead of polling regularly our Campaigns via the API to see if there are new submissions, we will use another new feature of the Beta Platform – the Callback URL. You can define your own Callback URL during the campaign creation process and this URL will be called whenever a new task has been finished by a worker. In addition to simply calling the URL, it also passes the following GET arguments:

• mw_taskId: The ID of the finished task
• mw_campaignId: The ID of the campaign to which the task belongs
• mw_workerId: The ID of the worker who has completed the task
• mw_campaignType: Either Basic or DynamicData based on the campaign to which the tasks belongs
• mw_hash: A security hash which can be used to authenticate that the call was actually made by an official Microworkers.com server. This hash is generated by concatenating the email address of your account with your API Key and then computing the md5 hash over it. As the API Key as well your email address should only to be known to you and the system this hash provides additional security when using the Callback feature.

Many thanks to one of our Beta testers who has suggested the additional parameters. They make life a lot easier.

Thus the final work flow can be described as:

• Use a designated Callback URL within the campaign creation
• Once a task has been finished and the this URL has been called validate the hash
• Use the API to fetch the details of the finished task
• Check if the worker has passed the validation
• Keep track of how many workers would approve/decline the comment based on the proof
• In case all reviews for one comment are in, approve or decline the comment in our Comment Moderation System based on the majority vote
• Rate the worker

Again we begin by updating our project structure thus creating the “callback.php” file.

 

We add the pre-computed hash to “settings.php” which we will use to authenticate the server handling the callback (line 60).

Further, we have to update our campaign settings in the “createCampaign.php” file to use the CallBackURL feature by setting it to call our “callback.php” file (line 71).

In order to keep track of the multiple reviews per comment we create an additional table in our database named “trackreview” with the following columns:

• commentId: Links the tracking entry to a specific comment
• posCount: Number of reviews which would have approved the comment
• negCount: Number of reviews which would have declined the comment

Now we are good to go and get to work on the newly generated “callback.php” file:

Again we start by including our “settings.php” file as well as the RESTClient library. Furthermore, we open a database connection. Then we check if the “mw_hash” parameter was set and if it matches our pre-computed hash (line 20). We continue by assigning the other parameters we will use to local variables (lines 22 to 24). We then create a new instance of our RESTClient and prepare it to fetch the task details. In order to build the complete URL path, we use the information received within the callback (lines 26 to35). By checking the Validation result of the submitted task we can decide if we have to rate the worker positively or negatively. The worker will only pass the validation if he has either submitted “y” in case he would have approved or “n” if he would have declined the comment. In case the validation is passed we decode the input of the worker and assign the result to a variable. As we only have one proof set we can always use the result of the first array entry (lines 40 to 42). In addition we decode the dynamic CSV file data associated with this task. By doing this we are able to retrieve the comment Id (lines 44 to 46). We then query our “trackreview” table if we have already received a review for this comment (lines 48 to 53). In case we haven’t, we create a new entry setting “commentId “ to our comment Id we have fetched from our task details and depending on the worker input we set “posCount” to 1 and “negCount” to 0 in case the worker input was “y”. In case the input was “n” we do the opposite by setting “posCount” to 0 and “negCount” to 1 (lines 79 to 87). If we have already received a review for this specific comment, we fetch the “posCount” and “negCount” values from the database entry and increment the appropriate value based on the worker input (lines 54 to 60). After updating our counters locally we write the updated version back to database (lines 60 to 68). Finally, we check if the sum of “posCount” and “negCount” equals the total number of reviews we have requested and if so we update the comment according to the majority vote (lines 70 to 78).

The rating is done by preparing the RESTClient pointing to the task’s root path URL and submitting the parameters “rating” and “comment”. Again as this an update action we set “PUT” as request method (lines 90 to 96).

That’s it. We now have fully automated Comment Moderation System and have reached the end of this tutorial series.

The same mechanism as described in this tutorial can also be applied to Image or Product Tagging, moderating Guestbook Entries, Video Categorization and many more. Basically to any application which would incorporate a majority vote.

We are really excited to see, what you would do with the API and in case you are planning a bigger project contact us for further support.

Thanks for joining us in this tutorial series and we hope you have enjoyed it.