Sharing Analytics API \ Initiate a new snapshot for shared content

Send a PUT request to this resource to initiate a snapshot of a previously published message.

Sharing Analytics API Resources/URI GET POST PUT DELETE
Sharing Analytics Snapshots /sharing/analytics/snapshots.<format> List all Snapshots – Initiate a new Snapshot –
Sharing Analytics Snapshot /sharing/analytics/snapshots/<sharing_analytics_snapshot_token>.<format> Read details of a Snapshot – – Delete a Snapshot

Workflow

1. Request: the code to send to the API

Send a PUT-Request to the resource /sharing/analytics/snapshots.<format> and include the structure below as POST-Data to initiate a snapshot of a previously published message. You can only request one snapshot at a time for a given message.

POST-Data to initiate a snapshot for a message:

		{
			"request": {
				"analytics": {
					"sharing": {
						"sharing_message_token": "<sharing_message_token>",
					}					
		    }
		  }
		}

Depending upon the number of users on behalf of whom you have shared the given message, it could take up to one hour to build the snapshot and you would have to leave your connection open during this time lapse.

To circumvent this problem, our API will return a sharing_analytics_snapshot_token that you can to use to retrieve the snapshot once it is available. You can either try repeatedly to retrieve the snapshot details until they are available or include the property pingback_uri in your POST-Data.

POST-Data to initiate a snapshot and to get notified once it has been build:

		{
			"request": {
				"analytics": {
					"sharing": {
						"sharing_message_token": "<sharing_message_token>",
						"pingback_uri": "http://www.your-server.com/pingback_handler.php"
					}					
		    }
		  }
		}

The pingback_uri is an url on your server that can handle the resultant response. After having build the snapshot, our API will POST the code below to the pingback_uri. Extract the sharing_analytics_snapshot_token and use it to retrieve the snapshot's details.

Result posted by our API to the given pingback uri:

	{
	  "response": {
	    "request": {
	      "date": "Fri, 27 Jan 2012 16:10:03 +0100",
	      "resource": "/sharing/analytics/snapshot.json",
	      "status": {
	        "flag": "success",
	        "code": 200,
	        "info": "Your request has been processed successfully"
	      }
	    },
	    "result": {
	      "data": {
	        "sharing_analytics_snapshot": {
	          "sharing_analytics_snapshot_token": "ace99ec8-969d-462d-a93d-ae896ddffdba",
	          "date_initiated": "Fri, 27 Jan 2012 16:08:37 +0100",
	          "date_finished": "Fri, 27 Jan 2012 16:10:03 +0100",
	          "sharing_message": {
	            "sharing_message_token": "221c7bdf-d2b7-4ee4-99f4-34d0d550ecf6",
	            "date_creation": "Tue, 24 Jan 2012 23:38:55 +0100",
	            "date_last_published": "Tue, 24 Jan 2012 23:38:56 +0100"
	          }
	        }
	      }
	    }
	  }
	}

2. Result: the code returned by the API

Contrary to the other API resources, you will not get a HTTP Status Code 200 if your request has been accepted.

HTTP Status Codes
  • The API may return one of the following status codes:
    • 201 : Your request has been received and the snapshot has been scheduled successfully;
    • 102 : Your request has been received but there is already a snapshot that is being build for the given message;

HTTP Status Code 201 - Snapshot initiated successfully:

		{
		  "response": {
		    "request": {
		      "date": "Fri, 27 Jan 2012 16:08:37 +0100",
		      "resource": "/sharing/analytics/snapshots.json",
		      "status": {
		        "flag": "scheduled",
		        "code": 201,
		        "info": "Your request has been received and scheduled to be processed"
		      }
		    },
		    "result": {
		      "data": {
		        "sharing_analytics_snapshot": {
		          "sharing_analytics_snapshot_token": "ace99ec8-969d-462d-a93d-ae896ddffdba",
		          "date_initiated": "Fri, 27 Jan 2012 16:08:37 +0100",
		          "sharing_message": {
		            "sharing_message_token": "221c7bdf-d2b7-4ee4-99f4-34d0d550ecf6",
		            "date_creation": "Tue, 24 Jan 2012 23:38:55 +0100",
		            "date_last_published": "Tue, 24 Jan 2012 23:38:56 +0100"
		          }
		        }
		      }
		    }
		  }
		}

HTTP Status Code 102 - There is already a snapshot being build for the given message:

		{
		  "response": {
		    "request": {
		      "date": "Fri, 27 Jan 2012 16:10:15 +0100",
		      "resource": "/sharing/analytics/snapshots.json",
		      "status": {
		        "flag": "processing",
		        "code": 102,
		        "info": "Your request is currently being processed"
		      }
		    },
		    "result": {
		      "data": {
		        "sharing_analytics_snapshot": {
		          "sharing_analytics_snapshot_token": "a5de98a6-50cc-4d69-916a-d1e7ca9bafd0",
		          "date_initiated": "Fri, 27 Jan 2012 16:10:11 +0100",
		          "sharing_message": {
		            "sharing_message_token": "221c7bdf-d2b7-4ee4-99f4-34d0d550ecf6",
		            "date_creation": "Tue, 24 Jan 2012 23:38:55 +0100",
		            "date_last_published": "Tue, 24 Jan 2012 23:38:56 +0100"
		          }
		        }
		      }
		    }
		  }
		}