Update Authorization and Timestamp usage

Followerwonk's Social Authority API was developed when it was a Moz
product. It used an Authorization method called MozSigned. Since
Followerwonk is no longer owned by, or associated with Moz, we've
renamed MozSigned to WonkSigned to avoid the confusion. We still accept
MozSigned, though, so existing code does not break.

The Timestamp parameter was originally called Expires, which allowed the
client to set the expiration policy. Long ago, while still a Moz
product, that strategy changed. Expires was renamed Timestamp, meant to
be the current time, allowing server-side request signature lifetime
policy management.

Just set Timestamp to the current time and if it is reasonably close to
current time when received by the server, it will be honored. A shorter
valid time window may be employed in the future.

Examples previously set a time in the future, compatible with the old
Expires policy. This update changes the examples to use current time
for all Timestamps.

Author: semifor

code-examples/perl.pl

@@ -15,11 +15,11 @@
 
 die "Must supply --id and --key" unless $id && $key;
 
-my $time      = time + 500;
-my $signature = hmac_sha1_hex( "$id\n$time", $key );
-my $auth      = "AccessID=$id;Timestamp=$time;Signature=$signature";
+my $now       = time;
+my $signature = hmac_sha1_hex( "$id\n$now", $key );
+my $auth      = "AccessID=$id;Timestamp=$now;Signature=$signature";
 
 while ( my $names = join ',', splice @ARGV, 0, 99 ) {
     say http( GET "$uri?screen_name=$names",
-        Authorization => "MozSigned $auth" )->as_json->response->dump;
+        Authorization => "WonkSigned $auth" )->as_json->response->dump;
 }

code-examples/php.php

@@ -1,25 +1,25 @@
-<?php 
+<?php
 	$uri = 'https://api.followerwonk.com/social-authority';
-	
+
 	// Enter your Access ID and Secret Key from http://followerwonk.com/social-authority below
 	$accessID = '';
 	$secretKey = '';
 
 
-	$time = time() + 500;
-	$signature = urlencode( base64_encode( hash_hmac( "sha1", "{$accessID}\n{$time}", $secretKey, true ) ) );
-	$auth = "AccessID={$accessID};Timestamp={$time};Signature={$signature}";
+	$now = time();
+	$signature = urlencode( base64_encode( hash_hmac( "sha1", "{$accessID}\n{$now}", $secretKey, true ) ) );
+	$auth = "AccessID={$accessID};Timestamp={$now};Signature={$signature}";
 
 	// Initialize an array of users. We call the API once for each of the usernames. There are more efficient alternatives.
 	$users = array('ebinnion', 'perigrin', 'randfish');
 
 	foreach($users as $user){
 		// Fetch the Json object and decode it into an array
 		$response = json_decode( file_get_contents( "{$uri}?screen_name={$user};{$auth}" ), true );
-		
+
 		// Use the commented API call below to get the result returned as an object
 		// $response = json_decode( file_get_contents( "{$uri}?screen_name=randfish;{$auth}" ));
-		
+
 		// Uncomment code block below to see entire Json response
 		// echo '<pre>';
 		// print_r($response);
@@ -34,4 +34,4 @@
 		echo $user_id . '<br>';
 		echo $social_authority . '<br>';
 	}
-?>
+?>

code-examples/python.py

@@ -35,7 +35,7 @@ class FollowerWonk(object):
     def social_authority(username):
         uri = 'https://api.followerwonk.com/social-authority'
 
-        datime = int(time() + 500)
+        datime = int(time())
 
         keyBin = follower_wonk_secret_key_str.encode('UTF-8')
         messageStr = "%s\n%s" % (follower_wonk_access_id_str, datime)

docs/Anatomy-of-a-Social-Authority-API-Call.md

@@ -1,12 +1,12 @@
 # Anatomy of a Social Authority API Call
 
-Every request to the Social Authority API follows the same basic format: 
+Every request to the Social Authority API follows the same basic format:
 
     http://api.followerwonk.com/social-authority?{screen_name};{user_id};{AccessID};{Timestamp};{Signature}
 
 Here's what each of these parts of this request do:
 
-* `http://api.followerwonk.com`	
+* `http://api.followerwonk.com`
 Access the API by calling the hostname of the service `api.followerwonk.com` and the Resource you’re making the request to `/social-authority`.
 
 * {screen_name} & {user_id}
@@ -21,9 +21,9 @@ These are query parameters that provide your credentials. For example:
 
 To use signed authentication, append the following three query string parameters:
 
-The AccessID parameter identifies the client in question. The value of this parameter must be your access ID, obtained when you generate yourAPI credentials.
-The Timestamp parameter is a Unix timestamp that indicates for how long this request is valid. This should be a time in the future, usually no more than several minutes later than the moment your client code initiates the transfer. Values that expire excessively far in the future will not be honored by the Mozscape API. Authentication timestamps must be in UTC in order to work properly.
-The Signature parameter is an HMAC-SHA1 hash of your Access ID (as it appears in the AccessID parameter), followed by a new line, followed by the Timestamp parameter, using your Secret Key. This hash must be base64 and URL-encoded before being placed in the request query string.
+The AccessID parameter identifies the client in question. The value of this parameter must be your access ID, obtained when you generate your API credentials.
+The Timestamp parameter is a Unix timestamp and indicates when the request was signed. This should be the current time. Values that are significantly from the current time will not be honored by the Social Authority API. Authentication timestamps must be in UTC in order to work properly.
+The Signature parameter is an HMAC-SHA1 hash of your Access ID (as it appears in the AccessID parameter), followed by a new line, followed by the Timestamp parameter, using your Secret Key. This hash must be Base64 and URL-encoded before being placed in the request query string.
 Once combined, a valid query string should look like the following:
 
 `AccessID=member-MDczMjM1NGUtN2Y3Ny01OGI0LThkOGUtYzhlYWVlYjcxMTZk;Timestamp=1225138899;Signature=LmXYcPqc%2BkapNKzHzYz2BI4SXfC%3D`
@@ -32,11 +32,11 @@ For example, the example request above should compute the HMAC-SHA1 of the follo
 
 `member-MDczMjM1NGUtN2Y3Ny01OGI0LThkOGUtYzhlYWVlYjcxMTZk <newline> 1225138899`
 
-Once the HMAC-SHA1 of this string is created, the binary form must be base64 encoded. The result of the base64 encoding must be URL-encoded. This method of authentication is complicated, but you can find helpful examples in several languages in our Sample Code.
+Once the HMAC-SHA1 of this string is created, the binary form must be Base64 encoded. The result of the Base64 encoding must be URL-encoded. This method of authentication is complicated, but you can find helpful examples in several languages in our Sample Code.
 
 ## ? and ;
 
-These little characters are important, so don’t miss them. The ? separates the main URL from the query parameters, and the ; goes between multiple parameters. You’ll see the ; used in the example for authentication, which is just 3 parameters required by the service.
+These little characters are important, so don't miss them. The ? separates the main URL from the query parameters, and the ; goes between multiple parameters. You’ll see the ; used in the example for authentication, which is just 3 parameters required by the service.
 All of these elements together give you a valid request:
 
     http://api.followerwonk.com/social-authority?screen_name=randfish;AccessID=member-MDczMjM1NGUtN2Y3Ny01OGI0LThkOGUtYzhlYWVlYjcxMTZk;Timestamp=1225138898;Signature=LmXYcPqc%2BkapNKzHzYz2BI4SXfC%3D

docs/code-examples/perl.md

@@ -23,14 +23,14 @@ Querying the Social Authority API is really quite simple. Here's an expanded exa
 
 	die "Must supply --id and --key" unless $id && $key;
 
-	my $time = time + 500;
-	my $signature = hmac_sha1_hex("$id\n$time", $key);
-	my $auth = "AccessID=$id;Timestamp=$time;Signature=$signature";
+	my $now = time;
+	my $signature = hmac_sha1_hex("$id\n$now", $key);
+	my $auth = "AccessID=$id;Timestamp=$now;Signature=$signature";
 
 	while ( my $names = join ',', splice @ARGV, 0,99 ) {
-	    say http( 
-	    	GET "$uri?screen_name=$names", 
-	    	     Authorization => "MozSigned $auth" 
+	    say http(
+	    	GET "$uri?screen_name=$names",
+	    	     Authorization => "WonkSigned $auth"
 	    )->as_json->response->dump;
 	}
 
@@ -48,30 +48,30 @@ We're stating that we'd like to use Perl 5.12.1. This version of Perl is the fir
 Next we bring in the external libraries we would like to use. There are three:
 
 	use HTTP::Thin::UserAgent;
-	use Getopt::Long; 
+	use Getopt::Long;
 	use Digest::HMAC_SHA1 qw(hmac_sha1_hex);
- 
+
 
 [`HTTP::Thin::UserAgent`][1] is a small HTTP client that makes doing API style requests easier. [`Getopt::Long`][2] is a standard command line argument parser, and it ships with the core Perl distribution. Finally [`Digest::HMAC_SHA1`][3] is what we'll use to sign our requests.
 
 Continuing on:
 
 	die "Must supply --id and --key" unless $id && $key;
- 
+
 If we don't have the information we need to sign the requests we throw an exception telling the user that they need to supply the required arguments.
 
 Next we set up our authentication credentials:
 
-	my $time = time + 500;
-	my $signature = hmac_sha1_hex("$id\n$time", $key);
-	my $auth = "AccessID=$id;Timestamp=$time;Signature=$signature";
+	my $now = time;
+	my $signature = hmac_sha1_hex("$id\n$now", $key);
+	my $auth = "AccessID=$id;Timestamp=$now;Signature=$signature";
 
 Then for batches of 100 names provided on the command line, we make the API request:
 
 	while ( my $names = join ',', splice @ARGV, 0,99 ) {
-	    say http( 
-	    	GET "$uri?screen_name=$names", 
-	    	     Authorization => "MozSigned $auth" 
+	    say http(
+	    	GET "$uri?screen_name=$names",
+	    	     Authorization => "MozSigned $auth"
 	    )->as_json->response->dump;
 	}