YottaSnap

Starting from version 1.20, YottaSnap service can be connected through clients with either REST or SOAP support. Tables below show the details of the API signature, the arguments to be passed to the service, and the resulting values returned from the service. While API version 1.10 remains effective, we strongly encourage users to upgrade to version 1.20 if possible.

Signature
SnapshotResult snapshotResult = GetSnapshotResult(Task task, TaskCredential taskCredential)

Task
Property	Description	Default
UniqueId	The unique ID assigned to you for your YottaSnap service. This property is mandatory.	N/A
TargetUriString	The full address to the web page to be snapshot. This property is mandatory. By default YottaSnap does not care about the final Uri that this TargetUriString brought it to. If there is a need to verify the final landed Uri, use any of these options: EnableExactMatch, FinalUriStringPrefix and IgnoreQueryString. Note: Uri ends with a slash "/" is considered a different address from Uri that does not end with "/". For instance, http://www.beyotta.com is not the same as http://www.beyotta.com/.	N/A
EnableExactMatch	Ensure the final Uri that YottaSnap landed at is exactly the same as what had been specified in TargetUriString. Do note that if this switch is set as true, addresses such as bit.ly or similar uri redirection services will not work. Besides, YottaSnap will also ignore both the FinalUriStringPrefix and IgnoreQueryString options.	false
FinalUriStringPrefix	If a value is supplied, YottaSnap will verify if the final landed Uri starts with the given FinalUriStringPrefix. It is considered "complete" if the verification is successful. This option works only if the EnableExactMatch is set as false.	Empty
IgnoreQueryString	Ignore the querystring that was automatically attached to the final landed Uri. For example, given a TargetUriString "http://www.yahoo.com", it may actually landed at "http://www.yahoo.com/?p=us". Set this option to true and YottaSnap will treat both of them the "same". This option works only if the EnableExactMatch is set as false and the FinalUriStringPrefix is empty.	false
Browser (New)	The browser that the engine uses to take the snapshot. Supported options: InternetExplorer [100], or Chromium [200].	IE
MasterTimeout	Timeout (in milliseconds) to be applied on the entire snapshot process. Supported range of values: 1000 to 150000.	30000
PageTimeout	Timeout (in milliseconds) to be applied on the page loading. Supported range of values: 0 to 150000.	25000
PageDelay	Delay (in milliseconds) to be applied once the page is loaded - this could be useful for sites tha are slow, pages containing many images, or pages with flash contents that takes time to load. Supported range of values: 0 - 15000.	3000
SnapshotWidth	Width of the image (in pixel) to be generated. Supported range of values: 128 - 16384. Note: If the targetted page has a width smaller than the requested width, width of the page will be used instead. This property has no effect if SnapshotMode is set as AutoWidthAndHeight.	1024
SnapshotHeight	Height of the image (in pixel) to be generated. Supported range of values: 128 - 16384. Note: If the targetted page has a height shorter than the requested height, height of the page will be used instead. This property has no effect if SnapshotMode is set as AutoWidthAndHeight.	768
SnapshotFormat	Output format of the snapshot image. Supported value: Jpeg [20], or Png [30].	Png
SnapshotQuality	Compression quality to be applied to the snapshot image. Supported range of values: 0 - 100. Note: This property has no effect if SnapshotFormat is set as Png.	80
SnapshotMode	The resizing mode of the snapshot, and the default mode is FixedWidthAndHeightRetainRatio. Please refer to the Snapshot Modes section for more information.	-
UpdateFrequency	This property has no effect on any fresh new request and will only be referenced in subsequent requests of the identical snapshot. It is in fact a cache expiry check. The system performs a validity check by comparing the date and time of the cached image against the UpdateFrequency value, and retakes the snapshot if the cached image has expired. For example, if there was a snapshot taken 1 hour ago, and a second request goes into the system requesting for the same snapshot with an UpdateFrequency of 6 hours, the cached version of the snapshot is served. However, if the value of UpdateFrequency is 20 minutes, the cached snapshot is discarded and a refreshed version will be served instead. Supported range of values: 5 - 43200 (minutes).	1440
EnablePostNotify	Switch the notification method to POST instead of the default GET. Refer to NotifyUriString for more information.	false
NotifyUriString	This property allows YottaSnap to inform the requestor once the snapshot is ready. It is optional and will only be enabled if it is supplied with a value. By default the system generates a GET request to the specified address, but you may set it as POST by using the EnablePostNotify switch. You may also add query strings to the address.	Empty

TaskCredential
This is optional. Specify null to this parameter if it is not relevant or not required.
Property	Description	Default
EnterActionUriString	Full address of the login page. This property is mandatory.	N/A
EnterActionElementId	ID of the DOM element (usually a button) on the login page that triggers the login action. This property is mandatory.	N/A
EnterFinalUriString	Uri to the page after the login procedure. This property is optional, however it will be set as EnterActionUriString if it is omitted.	-
IgnoreQueryString	Ignore the querystring that was automatically attached to the EnterFinalUriString.	false
CredentialParameters	A list of TaskCredentialParameters that encapsulates the information to be passed and applied during the authentication process.	-
ExitActionUriString	Full address of the logout page. This property is optional.	Empty

TaskCredentialParameter
Property	Description	Default
ParameterKey	ID of the DOM element to be passed over for credential authentication. This property is mandatory.	N/A
ParameterValue	Value of the DOM element to be passed over for credential authentication. This property is mandatory.	N/A

Once the request is submitted, YottaSnap responds to the requesting client by sending over the result wrapped in an SnapshotResult object.

SnapshotResult
Property	Description
ServiceStatus	The status of the request, which the value can be one of the followings: AccountInvalid [500] - The account is either invalid, suspended, or terminated. AccountInsufficientCredit [510] - This status is now deprecated. ArgumentCredentialParametersRequired [151] - One or more credential parameters are missing. This usually happens if a login URL is supplied without credential information attached. ArgumentInvalid [100] - One or more of the supplied arguments contained invalid value, or value of invalid format. ArgumentUniqueIdRequired [150] - The unique Id is missing. ArgumentOutOfRange [120] - Out-of-range value is detected in at least one of the supplied arguments. ProviderDBError [800] - Generic DB error. Contact us if you ever see this error. ProviderIOError [810] - Generic IO error. Contact us if you ever see this error. SnapshotCached [210] - The snapshot was cached and the UriString should contain the full address to this cached image. SnapshotQueued [200] - There is no cached image found or the cached image is due to be refreshed. The request is now in the processing queue. SnapshotSuspended [220] - The snapshot engine hit a road block while trying to capture the screen shot. In fact, the service has given up on the request after 5 failed tries. TargetUriInvalid [110] - The supplied TargetUriString is empty, invalid, or cannot be reached. Unknown [900] - There is an unexpected error somewhere.
TaskUniqueId	This is a unique Id assigned to this particular snapshot request. You may use this Id to inquire the status of the snapshot.
UriString	Full address to the snapshot image if the snapshot was cached. If this is a fresh new request and the snapshot is not ready to be consumed, value of this property is blank (i.e. empty string).
CurrentIndex	The current queue number of the request in the queue. The value of this property would only make sense if the snapshot is in Queued status.
TotalIndexes	Total number of requests in the queue, which indicates all requests that are to be processed, including requests initiated by other users. The value of this property would only make sense if the snapshot is in Queued status.

After you have successfully submitted a new snapshot request, you will be assigned with a TaskUniqueId that you could use to check the status of the request subsequently.

Signature
SnapshotResult snapshotResult = GetSnapshotResultById(Guid uniqueId, Guid taskUniqueId)

Property	Description	Default
UniqueId	The unique ID assigned to you for your YottaSnap service. This property is mandatory.	N/A
TaskUniqueId	The unique ID assigned to you when you first submitted the snapshot request. This property is mandatory.	N/A

And similar to the new snapshot request, the requesting client will be responded with the result wrapped in an SnapshotResult object.

Please note that if you submit a non-existent snapshot request, such as a request with an invalid TaskUniqueId, the status embedded in the SnapshotResult will be "Unknown".

YottaSnap service can be connected through clients with SOAP support. Tables below show the details of the API signature, the arguments to be passed to the service, and the resulting values returned from the service.

Signature
string uriString = GetSnapshotUriString(out ServiceStatus status, SnapTask request, SnapTaskCredential credential)

SnapTask
Property	Description	Default
UniqueId	The unique ID assigned to you for your YottaSnap service. This property is mandatory.	N/A
TargetUriString	The full address to the web page to be snapshot. This property is mandatory. By default YottaSnap does not care about the final Uri that this TargetUriString brought it to. If there is a need to verify the final landed Uri, use any of these options: EnableExactMatch, FinalUriStringPrefix and IgnoreQueryString. Note: Uri ends with a slash "/" is considered a different address from Uri that does not end with "/". For instance, http://www.beyotta.com is not the same as http://www.beyotta.com/.	N/A
EnableExactMatch	Ensure the final Uri that YottaSnap landed at is exactly the same as what had been specified in TargetUriString. Do note that if this switch is set as true, addresses such as bit.ly or similar uri redirection services will not work. Besides, YottaSnap will also ignore both the FinalUriStringPrefix and IgnoreQueryString options.	false
FinalUriStringPrefix	If a value is supplied, YottaSnap will verify if the final landed Uri starts with the given FinalUriStringPrefix. It is considered "complete" if the verification is successful. This option works only if the EnableExactMatch is set as false.	Empty
IgnoreQueryString	Ignore the querystring that was automatically attached to the final landed Uri. For example, given a TargetUriString "http://www.yahoo.com", it may actually landed at "http://www.yahoo.com/?p=us". Set this option to true and YottaSnap will treat both of them the "same". This option works only if the EnableExactMatch is set as false and the FinalUriStringPrefix is empty.	false
MasterTimeout	Timeout (in milliseconds) to be applied on the entire snapshot process. Supported range of values: 1000 to 150000.	30000
PageTimeout	Timeout (in milliseconds) to be applied on the page loading. Supported range of values: 0 to 150000.	25000
PageDelay	Delay (in milliseconds) to be applied once the page is loaded - this could be useful for sites tha are slow, pages containing many images, or pages with flash contents that takes time to load. Supported range of values: 0 - 15000.	3000
SnapshotWidth	Width of the image (in pixel) to be generated. Supported range of values: 128 - 16384. Note: If the targetted page has a width smaller than the requested width, width of the page will be used instead. This property has no effect if SnapshotMode is set as AutoWidthAndHeight.	1024
SnapshotHeight	Height of the image (in pixel) to be generated. Supported range of values: 128 - 16384. Note: If the targetted page has a height shorter than the requested height, height of the page will be used instead. This property has no effect if SnapshotMode is set as AutoWidthAndHeight.	768
SnapshotFormat	Output format of the snapshot image. Supported value: Jpeg, or Png.	Png
SnapshotQuality	Compression quality to be applied to the snapshot image. Supported range of values: 0 - 100. Note: This property has no effect if SnapshotFormat is set as Png.	80
SnapshotMode	The resizing mode of the snapshot, and the default mode is FixedWidthAndHeightRetainRatio. Please refer to the Snapshot Modes section for more information.	-
UpdateFrequency	This property has no effect on any fresh new request and will only be referenced in subsequent requests of the identical snapshot. It is in fact a cache expiry check. The system performs a validity check by comparing the date and time of the cached image against the UpdateFrequency value, and retakes the snapshot if the cached image has expired. For example, if there was a snapshot taken 1 hour ago, and a second request goes into the system requesting for the same snapshot with an UpdateFrequency of 6 hours, the cached version of the snapshot is served. However, if the value of UpdateFrequency is 20 minutes, the cached snapshot is discarded and a refreshed version will be served instead. Supported range of values: 5 - 43200 (minutes).	1440
EnablePostNotify	Switch the notification method to POST instead of the default GET. Refer to NotifyUriString for more information.	false
NotifyUriString	This property allows YottaSnap to inform the requestor once the snapshot is ready. It is optional and will only be enabled if it is supplied with a value. By default the system generates a GET request to the specified address, but you may set it as POST by using the EnablePostNotify switch. You may also add query strings to the address.	Empty

SnapCredential
This is optional. Specify null to this parameter if it is not relevant or not required.
Property	Description	Default
EnterActionUriString	Full address of the login page. This property is mandatory.	N/A
EnterActionElementId	ID of the element (usually a button) on the login page that triggers the login action. This property is mandatory.	N/A
EnterFinalUriString	Uri to the page after the login procedure. This property is optional, however it will be set as EnterActionUriString if it is omitted.	N/A
IgnoreQueryString	Ignore the querystring that was automatically attached to the EnterFinalUriString.	false
InputParameters	A string based dictionary that encapsulates the information to be passed and applied during the authentication process.	-
ExitActionUriString	Full address of the logout page. This property is optional.	Empty

Once the request is submitted, YottaSnap responds to the requesting client by sending over two parameters, one being the uri to the snapshot image, and another being the request status.

Parameters	Description
uriString	Full address to the snapshot image if the snapshot was cached. If this is a fresh new request and the snapshot is not ready to be consumed, value of this parameter will be blank (i.e. empty string).
status	The status of the request, which the value can be one of the followings: AccountInsufficientCredit - The account does not have sufficient credits for this request. AccountInvalid - The account is either invalid or in-active. ArgumentInvalid - Invalid value is found in at least one of the supplied arguments. ArgumentOutOfRange - Out-of-range value is detected in at least one of the supplied arguments. SnapTaskCached - The snapshot was cached and the imageUri should contain the full address to this cached image. SnapTaskQueued - There is no cached image found or the cached image is due to be refreshed. The request is now in the processing queue. TargetUriInvalid - The supplied TargetUriString is empty, invalid, or cannot be reached. Unknown - There is an unexpected error somewhere.

This API allows the caller to inquire the queue status of a particular request.

Signature
int index = GetSnapshotIndex(out int totalIndexes, SnapTask request)

SnapTask
Property	Description	Default
UniqueId	The unique ID assigned to you for your YottaSnap service. This property is mandatory.	N/A
TargetUriString	The full address to the web page to be snapshot. This property is mandatory. Note: Uri ends with a slash "/" is considered a different address from Uri that does not end with "/". For instance, http://www.beyotta.com is not the same as http://www.beyotta.com/.	N/A
SnapshotWidth	Width of the image (in pixel) to be generated. Supported range of values: 128 - 16384. Note: This property will be ignored if the SnapshotMode is set as AutoWidthAndHeight.	1024
SnapshotHeight	Height of the image (in pixel) to be generated. Supported range of values: 128 - 16384. Note: This property will be ignored if the SnapshotMode is set as AutoWidthAndHeight.	768
SnapshotFormat	Output format of the snapshot image. Supported value: Jpeg, or Png.	Png
SnapshotMode	The resizing mode of the snapshot, and the default mode is FixedWidthAndHeightRetainRatio. Please refer to the Snapshot Modes section for more information.	-
Notes: Other properties such as MasterTimeout are not in use and will be ignored if supplied with a value.

And the response from YottaSnap would be two parameters as below:

Parameters	Description
index	The current queue number of the request in the queue.
totalIndexes	Total number of requests in the queue. This number indicates all requests that are to be processed, including requests initiated by others.

There are altogether 6 snapshot modes for the user to choose from, and how these modes work is best explained with pictures. Given an example that you have a web page in the size of 300 (W) x 287 (H), different snapshot mode produces different result:

Mode	Sample
AutoWidthAndHeight [90] Original size with no additional thumbnailing effect.	300 (W) x 287 (H)
FixedWidth [10] Width of the image is fixed, height varies according to ratio.	200 (W) x 191 (H)
FixedHeight [20] Height of the image is fixed, width varies according to ratio.	209 (W) x 200 (H)
FixedWidthAndHeightAutoCrop [30] Width and height are fixed. Image is scaled to fill the largest possible dimension and cropped.	200 (W) x 200 (H)
FixedWidthAndHeightRetainRatio [35] Width and height are fixed. Image is scaled to fit the largest possible dimension and the canvas is filled with white (Jpeg) or transparent (Png) as background color.	200 (W) x 200 (H)
FixedWidthOrHeightRetainRatio [40] This is the default mode. System picks the best between Fixed Width and Fixed Height according to the largest possible dimension. In this example Fixed Width was selected as the largest dimension is 200 (W).	200 (W) x 191 (H)