DSUMO Computing - API

Introduction

The DSUMO API is the mechanism of executing microcompute transactions, retrieving results, managing functions, and obtaining insignt into the DSUMO platform.

The API is designed to be lightweight, and to that end the data structures, field names, and constants used by the API are given in as few characters as possible. The API supports two types of data structures: JSON and XML.

The JSON format used with DSUMO is the one defined at JSON.org. It typically uses braces ({ }) to enclose objects, brackets ([ ]) to enclose arrays, has quoted object names, and all non-numeric values are quoted. (This is just an overview; consult JSON.org for more information).

JSON is the recommended request/response format for DSUMO, as JSON is used in much of the DSUMO platform aside from the API. Further, data passed to and from microcompute transactions and microcompute operations will be in the JSON format. JSON is also more lightweight than XML.

XML consumed and returned by the DSUMO API does not conform to an existing document format, does not have an associated namespace, and does not contain an XML declaration when the API responds (a request may have an XML declaration, but it is not recommended). Whenever possible, XML is structured to match its JSON counterpart. As such, care should be taken when constructing XML for and parsing XML from the API.

API Basics

The DSUMO Computing API is called via HTTP, using the POST method. They payload of the HTTP request should contain either JSON or XML, and be encoded using UTF-8.

The content-type of an HTTP request with a JSON payload should be application/json, and the HTTP response will likewise have the same content type. The correct content type for an XML request (and response) is application/xml. The Content-Type header should further specify that the character set is UTF-8 (if the charset parameter is not specified for the request, it will be assumed to be UTF-8).

By default, returned data will be in the same format as that of the request.

Sample HTTP headers are shown below for a JSON request/response pair.

API calls may be tested in our sandbox environment by replacing api.dsumo.net with api.sandbox.dsumo.net in any of the cases shown below. When URLs for service nodes are returned, they will likewise have the suffix sandbox.dsumo.net.

Functions

Functions can be added, modified, or removed both on the KisoLabs website and via the API. The API is accessed at the following URL:

http://api.dsumo.net/func[?f=json|xml]

The API may be accessed via SSL by replacing http:// with https:// in any of the circumstances illustrated below.

The query string parameter supplied with the URL, f=json|xml, specifies the format of the request. This parameter is optional, however if it is not given then the first character of the HTTP content must be { for JSON or < for XML.

Common request parameters

All calls to the API must include the following two parameters:

Parameter	Name	Type
s_guid	Service GUID	GUID1	This is the GUID provided to you upon creating your DSUMO Computing service. It is used to authenticate API requests.
act	Action	string	The action to be performed: get - Get a function. add - Add a new function. chg - Change an existing function. del - Delete a function. lst - Lists all functions.

¹ GUID is a 42 character hexadecimal string. The GUID is not case sensitive.

All responses from the API will include the following two parameters:

Parameter	Name	Type
s	Status	integer	The status of the API call: 100 - Success
s_c	Readable Status	string	The status of the API call in human-readable format. (These values are for reference only, and should not be relied upon to be consistent).

For each action, additional parameters may be required. Those parameters are described below for each action.

get

Request parameter

Parameter	Name	Type
id	Identifier	integer	The identifier of a function.

Response fields

Parameter	Name	Type
id	Identifier	integer	The identifier of the function.
name	Name	string	The name of the function.
cmt	Comment	string	A comment describing the function.
func	Function body	string	The body of the function.

Sample Request

JSON | XML

Sample Response

JSON | XML

add

Request parameters

Parameter	Name	Type
name	Name	string	The name of the function.
cmt	Comment	string	A comment describing the function.
func	Function body	string	The body of the function.

Response field

Parameter	Name	Type
id	Identifier	integer	The identifier assigned to the function.

Sample Request

JSON | XML

Sample Response

JSON | XML

chg

Request parameters

Parameter	Name	Type
id	Identifier	integer	The identifier of the function.
name	Name	string	The name of the function.
cmt	Comment	string	A comment describing the function.
func	Function body	string	The body of the function.

Response field

Parameter	Name	Type
id	Identifier	integer	The identifier of the function.

Sample Request

JSON | XML

Sample Response

JSON | XML

del

Request parameter

Parameter	Name	Type
id	Identifier	integer	The identifier of the function.

Response field

Parameter	Name	Type
id	Identifier	integer	The identifier of the function.

Sample Request

JSON | XML

Sample Response

JSON | XML

lst

Request parameter

Parameter	Name	Type
The list action has no additional parameters.

Response field

Parameter	Name	Type
count	Count	integer	The number of functions returned.
lst	List	array1	An array of function identifiers.

¹The array data type is delivered as an array in JSON. When serialized to XML, each element of the array is placed within item tags. For example:

Sample Request

JSON | XML

Sample Response

JSON | XML

Microcompute Transactions

Unlike functions, which are manipulated through a call to a single URL, microcompute transactions require that your applications leverage the distributed nature of DSUMO's architecture.

Status URL

To obtain the status of all of your pending and/or completed microcompute transactions, a list (lst) action is called at the following URL:

http://status.dsumo.net/mt[?f=json|xml|form]

Execute URL

To execute a microcompute transaction, an execute (exe) action is called at this URL, which is specific to your service:

http://[service node host].dsumo.net/mt[?f=json|xml]

The hostname assigned to your service can be found in the DSUMO management interface at the KisoLabs website (when logged into your account).

Result / Get URL

Upon establishing your DSUMO Computing service with KisoLabs, a number of service nodes were assigned to your account. Those service nodes are responsible for disseminating the workload of your microcompute transactions to the web browsers of the internet at large. The results of your microcompute transactions also are available at these URLs.

When a microcompute transaction is executed, part of the return value will contain the appropriate URL from which to retrieve the result(s). This URL can also be obtained by calling a list (lst) action from the first URL listed above. If your API call (or API defaults) are set to return a result asynchronously to your own URL, then it is not necessary to retrieve the result.

The result retrieval URL will follow the following general form wherein XXXX represents a 4 character alphanumeric string:

http://esnXXXX.dsumo.net/mt[?f=json|xml]

In the event that an action is called to a URL that does not support it, you may receive an error stating that the API call is not valid. In the case of attempting to retrieve a result, you may receive an error stating that the result could not be found. This indicates that either the microcompute transaction has not yet completed or that the URL is incorrect for that particular result.

Common request parameters

All calls to the API must include the following two parameters:

Parameter	Name	Type
guid	API GUID	GUID1	This is the GUID provided to you upon creating your DSUMO Computing service. It is used to authenticate API requests.
act	Action	string	The action to be performed: exe - Execute a microcompute transaction. get - Retrieve a microcompute transaction. res - Retrieve results of a microcompute transaction. lst - List microcompute transactions. com - List completed/uncollected microcompute transaction results. abt - Abort a microcompute transaction.

¹ GUID is a 42 character hexadecimal string. The GUID is not case sensitive.

All responses from the API will include the following two parameters:

Parameter	Name	Type
s	Status	integer	The status of the API call: 100 - Success
s_c	Readable Status	string	The status of the API call in human-readable format. (These values are for reference only, and should not be relied upon to be consistent).

exe

Executes a microcompute transaction.

Request parameters

Parameter	Name	Type
f_name	Function Name	string	The name of the function to be executed.
data	Data	object1	The dataset that will be available to the function.
r_m	Return Method	integer (optional)	The return method of the microcompute transaction result(s): 0 - The microcompute transaction results will be later retrieved via a call to the DSUMO API. 1 - Upon completion of a microcompute transaction, DSUMO will call the URL specified with a notification that the microcompute transaction is complete, and from where it can be retrieved. 2 - Upon completion of a microcompute transaction, DSUMO will call the URL specified with the full dataset of the result(s).
r_u	Return URL	URL2 (optional)	The URL to which the results or reference to the results of a microcompute transaction are returned. (This is required if the return method is set to 1 or 2 and no return URL is configured in the API defaults of the service).
r_t	Return Type	integer (optional)	The return type of the microcompute transaction result(s): 0 - JSON (default) 1 - XML Note that this is only relevant when the return method is set to 1 or 2 (using a callback URL). When using the API to retrieve results, the return type can be specified on a call-by-call basis which will override this setting.
s_flag	Sandbox Flag	integer (optional)	Indicates that the microcompute transaction should be executed in sandbox mode: 0 - Sandbox mode is off. (default) 1 - Sandbox mode is on. This flag is used when testing the execution of microcompute transactions. If it is on, the transaction will not be processed publicly nor automatically.

¹ The object type is any valid JavaScript object which can be serialized to JSON. When accessing the API using the JSON format, the object will be a part of the same JSON construct as the request. When accessing the API using the XML format, the object will also be a JSON string.

² The URL type must contain a string starting with http:// or https://, where the totality of the string is a valid and accessible URL.

Response field

Parameter	Name	Type
mt_guid	Microcompute Transaction GUID	GUID1	A GUID that refers to the transaction being retrieved.

¹ GUID is a 42 character hexadecimal string. The GUID is not case sensitive.

get

Retrieves the microcompute transaction specified. The return values do not include the results of the transaction. The get action may be called at any time during execution or after completion of the transaction.

Request parameters

Parameter	Name	Type
mt_guid	Transaction GUID	GUID1	A GUID that refers to the transaction being retrieved.

¹ GUID is a 42 character hexadecimal string. The GUID is not case sensitive.

Response field

Parameter	Name	Type
mt_guid	Transaction GUID	GUID1	A GUID that refers to the transaction being retrieved.
mt_st	Transaction State	integer	The numeric state of the transaction.
mt_st_n	Transaction State Name	string	The shorthand name of the transaction state.
mt_st_d	Transaction State Description	string	The description of the transaction state.
mt_cr_on	Transaction Created On	datetime (UTC)	The date and time on which the transaction was created.
mt_ex_on	Transaction Executed On	datetime (UTC)	The date and time on which the transaction was executed.
mt_cm_on	Transaction Completed On	datetime (UTC)	The date and time on which the transaction was completed.
r_m	Return Method	integer	The return method of the microcompute transaction result(s): 0 - The microcompute transaction results will be later retrieved via a call to the DSUMO API. 1 - Upon completion of a microcompute transaction, DSUMO will call the URL specified with a notification that the microcompute transaction is complete, and from where it can be retrieved. 2 - Upon completion of a microcompute transaction, DSUMO will call the URL specified with the full dataset of the result(s).
r_u	Return URL	URL2 (conditional)	The URL to which the results or reference to the results of a microcompute transaction are returned. This field is only returned when return method has a value of either 1 or 2.
r_t	Return Type	integer (conditional)	The return type of the microcompute transaction result(s): 0 - JSON (default) 1 - XML 2 - HTML Form This field is only returned when return method has a value of either 1 or 2.
s_flag	Sandbox Flag	integer (optional)	Indicates that the microcompute transaction will be (or was) executed in sandbox mode: 0 - Sandbox mode is off. (default) 1 - Sandbox mode is on. This field is only returned in the case that the value of the sandbox flag is 1 (sandbox mode is on).
f_name	Function Name	string	The name of the function executed.
data	Data	object3	The dataset made available to the function.

¹ GUID is a 42 character hexadecimal string. The GUID is not case sensitive.

² The URL type must contain a string starting with http:// or https://, where the totality of the string is a valid and accessible URL.

³ The object type is any valid JavaScript object which can be serialized to JSON. When accessing the API using the JSON format, the object will be a part of the same JSON construct as the request. When accessing the API using the XML format, the object will also be a JSON string.

res

Retrieves the results of the microcompute transaction specified. The res action should only be called after completion of the transaction.

Request parameter

Parameter	Name	Type
mt_guid	Transaction GUID	GUID1	A GUID that refers to the transaction for which results are being retrieved.

¹ GUID is a 42 character hexadecimal string. The GUID is not case sensitive.

Response fields

Parameter	Name	Type
mt_guid	Transaction GUID	GUID1	A GUID that refers to the transaction being retrieved.
mt_st	Transaction State	integer	The numeric state of the transaction.
mt_st_n	Transaction State Name	string	The shorthand name of the transaction state.
mt_st_d	Transaction State Description	string	The description of the transaction state.
mt_cr_on	Transaction Created On	datetime (UTC)	The date and time on which the transaction was created.
mt_ex_on	Transaction Executed On	datetime (UTC)	The date and time on which the transaction was executed.
mt_cm_on	Transaction Completed On	datetime (UTC)	The date and time on which the transaction was completed.
results	Results	collection2	The set of results generated by the microcompute transaction. See the result collection item fields below.

¹ GUID is a 42 character hexadecimal string. The GUID is not case sensitive.

² Collection is not a data type per se. When using the API with the JSON request/response format, the collection will be an array of objects. When using the API with the XML format, the collection will be an XML node list. For the results field, each element of the results collection will be enclosed in <result></result> tags.

Result collection item fields

The fields listed below will be contained within the results field of the res action.

Parameter	Name	Type
mo_guid	Microcompute Operation GUID	GUID1	A GUID that refers to the microcompute operation from which the result was generated.
mo_st	Microcompute Operation State	integer	The numeric state of the microcompute operation.
mo_st_n	Microcompute Operation State Name	string	The shorthand name of the microcompute operation state.
mo_st_d	Microcompute Operation State Description	string	The description of the microcompute operation state.
mo_cr_on	Microcompute Operation Created On	datetime (UTC)	The date and time on which the microcompute operation was created.
mo_ex_on	Microcompute Operation Executed On	datetime (UTC)	The date and time on which the microcompute operation was executed.
f_name	Microcompute Function Name	string	The name of the function that was executed in the context of the microcompute operation.
md_r_state	Microcompute Data Result State	integer	The numeric state of the microcompute data storage instance.
md_r_data	Microcompute Data Result Data	object2	The resultant data of the microcompute operation as returned by the function.

¹ GUID is a 42 character hexadecimal string. The GUID is not case sensitive.

² The object type is any valid JavaScript object which can be serialized to JSON. When accessing the API using the JSON format, the object will be a part of the same JSON construct as the request. When accessing the API using the XML format, the object will also be a JSON string.

lst

Lists the microcompute transactions associated with your DSUMO Computing service, according to the parameters specified. This will not return the results of the transaction(s), but will include the URL of the server(s) from which more information (including results) pertaining to the MTs can be obtained.

Request parameters

Parameter	Name	Type
l_u_s	List Updated Since	datetime	Microcompute transactions that were created or updated since this date and time will be returned.

Response field

Parameter	Name	Type
mt_guid	Microcompute Transaction GUID	GUID1	A GUID that refers to the transaction being retrieved.
esn_url	External Server URL	URL	The URL of the server on which the microcompute transaction is available, both for get and res actions.
mt_st	Transaction State	integer	The numeric state of the transaction.
mt_st_n	Transaction State Name	string	The shorthand name of the transaction state.
mt_cr_on	Transaction Created On	datetime (UTC)	The date and time on which the transaction was created.
mt_ex_on	Transaction Executed On	datetime (UTC)	The date and time on which the transaction was executed.
mt_cm_on	Transaction Completed On	datetime (UTC)	The date and time on which the transaction was completed.

¹ A GUID is a 42 character hexadecimal string.

com

Lists the microcompute transactions associated with your DSUMO Computing service which have completed/uncollected results, according to the parameters specified. This will not return the results of the transaction(s).

The com action is useful if you wish to poll DSUMO for results, or if you are implementing callback results but want to ensure that no callbacks were missed by your host(s).

Request parameters

Parameter	Name	Type
cr_min	Created on (Minimum)	datetime (UTC)	Microcompute transactions that were created since this date and time will be returned.

Response field

Parameter	Name	Type
mt_guid	Microcompute Transaction GUID	GUID1	A GUID that refers to the transaction for which there are completed/uncollected results.
c	Count	c	The number of completed/uncollected results for the microcompute transaction.

¹ A GUID is a 42 character hexadecimal string.

abt

Aborts the execution of a microcompute transaction. This will only abort a transaction that has a status other than COMPLETE (100). The applicable fee(s) for any microcompute operations that were already completed within this transaction will be charged to your account. It is not guaranteed that the transaction will be aborted immediately.

Request parameter

Parameter	Name	Type
mt_guid	Transaction GUID	GUID1	A GUID that refers to the transaction for which results are being retrieved.

¹ GUID is a 42 character hexadecimal string. The GUID is not case sensitive.

Response fields

No additional parameters are returned for an abort request. The status returned will specify the success (or failure) of the abort action.

Information - General

This part of the API provides information about the DSUMO infrastructure, details of microcompute transactions, and errors that have occurred while processing microcompute operations. In some cases the information may be stored on a particular service node, and the response from the API will indicate the URL that must be used for subsequent requests. The general information URL follows this format:

http://api.dsumo.net/info[?f=json|xml]

If the response indicates the URL needed to obtain details from a specific service node, the information API at that node will support different parameters and responses than the general information URL. For details, see the section Information - Service Node below.

The query string parameter supplied with the url, f=json|xml, specifies the format of the request. This parameter is optional, however if it is not given then the first character of the HTTP content must be { for JSON or < for XML.

Common request parameters

All calls to the API must include the following two parameters:

Parameter	Name	Type
s_guid	Service GUID	GUID1	This is the GUID provided to you upon creating your DSUMO Computing service. It is used to authenticate API requests.
act	Action	string	The action to be performed: stats - Get infrastructure and microcompute operation statistics. log - Get log messages that have been generated while processing microcompute transactions. mo - Get details about a microcompute operation.

¹ GUID is a 42 character hexadecimal string. The GUID is not case sensitive.

All responses from the API will include the following two parameters:

Parameter	Name	Type
s	Status	integer	The status of the API call: 100 - Success
s_c	Readable Status	string	The status of the API call in human-readable format. (These values are for reference only, and should not be relied upon to be consistent).

For each action, additional parameters may be required. Those parameters are described below for each action.

stats

The stats action will return any or all of the following statistic types, depending on which is passed to the types parameter:

if - Infrastructure load. Metrics are returned that indicate the global utilization and capacity of the DSUMO infrastructure. (Defaults to most recent data).

• If the summary flag is on, the values returned will be averages for that period.
• If the summary flag is off, infrastructure load will be returned for the specified period in 15 minute increments.

mo - Microcompute operations. (Defaults to the past 60 minutes).

• If the summary flag is on, the values returned will be the sum of values for that period.
• If the summary flag is off, the GUIDs of all microcompute transactions executed within the specified period will be returned, grouped by the service node that executed the transactions. A URL to each service node's information API will be provided, and via that URL summary data or a list of microcompute transactions may be retrieved.

func - Functions.

• If the summary flag is on, the values returned will be the number of functions that match each result field.
• If the summary flag is off, functions will be listed for each of these categories: approved, executed, completed, error, and other.

Request parameter

Parameter	Name	Type
types	Statistic Types	commaList1 (optional)	A list of all statistic types desired to be returned (see above). The default is to return all stat types.
summary	Summary Flag	binary2 (optional)	1 = Show summary only (average or sums of data found in the Lookback Time specified). This is the default. 0 = Show detailed data found in the Lookback Time specified.
lookback	Lookback Time	timeLength3 (optional)	The length of time to look back. (The time length specified is subtracted from the current date and time, and any applicable data between those two datetimes will be used to retrieve the return value(s)). The default varies based upon the Statistic Type(s) chosen (see above).

¹ commaList is not a data type per se; it is actually a string. However, the API must receive this string as a comma-delimited list in the general form: item1,item2,[..],itemZ

² binary is not a data type per se; it is actually an integer value that must be zero or one, and must be one digit in length.

³ If timeLength is given as an integer, it will be interpreted as seconds. timeLength may also be given as a shorthand notation for a time duration in the form: x[s|m|h|d|M|y] where x is an integer representing the number of time units and s = seconds, m = minutes, h = hours, d = days, M = months, y = years. For example, 45m means 45 minutes and 6M means 6 months.

Response

The response received will depend upon whether the summary flag is on or off, and the statistic type(s) requested. When the summary flag is on, the response will follow this hierarchical format:

• Statistic Type 1
  • Field 1
  • Field 2
  • [...]
  • Field Z
• [...]
• Statistic Type Z
  • Field 1
  • Field 2
  • [...]
  • Field Z

Response fields (Infrastructure Load)

Parameter	Name	Type
mo_qd	MO Queue Depth	integer	The number of microcompute operations pending execution. This is averaged globally across all service nodes.
mo_wt	MO Queue Wait Time	integer	The number of seconds between the time the last MO was added to the queue, and the time the oldest unexecuted MO was added to the queue. This is averaged globally across all service nodes.
mn_av	MNs Available	integer	The number of microcompute nodes available to process microcompute operations. This is averaged globally across all service nodes (because microcompute nodes connect to service nodes in a round-robin fashion, the average number of MNs across all nodes should roughly equal the total number of MNs available).
dt	Date/time	datetime1	The date and time at which this statistic was captured. Note: If the summary flag is set to 1 this will return the most recent date/time of the available statistics.

¹ datetime will be in the form yyyy-MM-dd hh:mm:ss, and will be in UTC.

Response fields (Microcompute Operations)

Parameter	Name	Type
mo_st_g	MOs Started Globally	integer	The number of microcompute operations executed globally.
mo_cm_g	MOs Completed Globally	integer	The number of microcompute operations successfully completed globally.
mo_st	MOs Started	integer	The number of microcompute operations executed under the service making the API request.
mo_cm	MOs Completed	integer	The number of microcompute operations successfully completed under the service making the API request.
d_kb	Data in KB	integer	The number of kilobytes transferred in MO data sets.
dt	Date/time	datetime1	The date and time at which this statistic was captured. Note: If the summary flag is set to 1 this will return the most recent date/time of the available statistics.

¹ datetime will be in the form yyyy-MM-dd hh:mm:ss, and will be in UTC.

Response fields (Functions)

Parameter	Name	Type
total	Total	integer	A count of all functions available to the service making the API request.
approved	Approved	integer	A count of all functions available to the service making the API request that have been approved for execution.
executed	Executed	integer	A count of all functions available to the service making the API request that have been executed at least once.
completed	Completed	integer	A count of all functions available to the service making the API request that have completed execution successfully the last time they were called.
error	Error	integer	A count of all functions available to the service making the API request that have had at least one runtime error in the specified period (log messages of the severities error and fatal are included). Note that this is the only field for which the lookback time is relevant.

log

The log action will return a list of all log messages thrown by microcompute transactions in the given time frame. Each log message will be accompanied by a service node URL from which further information may be obtained.

Request parameters

Parameter	Name	Type
type	Log Message Types	commaList1 (optional)	A list of log types. Log messages matching any of these types will be returned: caughtException - An exception that was caught by the data container executing the MO. This is equivalent to an unhandled exception in the context of the microcompute function. This is always a fatal error. userThrown - An exception that was caught by code within the microcompute function. The severity of this log message is not rigidly defined by DSUMO and will depend upon the implementation done by the developer. illegalFuncCall - A native JavaScript function which is prohibited by the DSUMO Framework was called by the microcompute function. This is always a fatal error. The default is to return all log message types.
sev	Log Message Severities	commaList1 (optional)	A list of log message severities. Log messages matching any of these severities will be returned: debug - Intended for messages that aid in debugging (this severity will only be logged by microcompute transactions run in the sandbox). info - Informational message. warning - Indicates something is wrong, but there was no failure in execution. error - Indicates a non-fatal failure in execution. fatal - Indicates that the microcompute operation failed at the point that this error was generated, and could not run to completion. The default is to return all log message severities.
start_date	Start Date/Time	datetime2 (optional)	Log messages that were generated on or after this date/time will be returned. Default is zero time (no limit on the start date/time).
end_date	End Date/Time	datetime2 (optional)	Log messages that were generated on or before this date/time will be returned. Default is the current date/time.
mt_guid	Microcompute Transaction GUID	GUID3 (optional)	Log messages that were generated during this transaction will be returned. Default is no restriction.
mo_guid	Microcompute Operation GUID	GUID3 (optional)	Log messages that were generated during the execution of this microcompute operation will be returned. Default is no restriction. If mt_guid is also specified, it will be ignored in favor of mo_guid.

¹ commaList is not a data type per se; it is actually a string. However, the API must receive this string as a comma-delimited list in the general form: item1,item2,[..],itemZ

² datetime is not a data type per se; it is actually a string value that represents a date (and optionally a time). The string value will be parsed and will assumed to be in UTC. An offset may be specified if the date/time is not in UTC, by appending a space followed by a plus (+) or minus (-) and then an integer value indicating the UTC offset (e.g. 2012-09-17 22:00:00 -4 would be equivalent to 2012-09-18 02:00:00 UTC). The preferred date/time format is yyyy-MM-dd[ hh:mm:ss]. If a time component is not specified then the time will be assumed to be 00:00:00 (midnight) on the date specified.

³ GUID is a 42 character hexadecimal string. The GUID is not case sensitive.

Response fields

Parameter	Name	Type
mt_g	Microcompute Transaction GUID	GUID1	The microcompute transaction for which this log message has been generated.
mo_g	Microcompute Operation GUID	GUID1	The microcompute operation for which this log message has been generated.
f_n	Microcompute Function Name	string	The microcompute function for which this log message has been generated.
type	Log Message Type	string	The type of log message: caughtException, userThrown, or illegalFuncCall.
sev	Log Message Severity	string	The severity of the log message: debug, info, warning, error or fatal.
dt	Date/time	datetime2	The date and time on which the log message was generated (in UTC).
sn_host	Service Node Host	string	The host name of the service node from which more details about this log message can be obtained.

¹ GUID is a 42 character hexadecimal string. The GUID is not case sensitive.

mo

The mo action will return the host name of the service node that was responsible for running the microcompute transaction specified. Details about the transaction, including all microcompute operations, will be available from the information API at that host.

Request parameter

Parameter	Name	Type
mt_guid	Microcompute Transaction GUID	GUID1	The microcompute transaction about which the information should be retrieved.

¹ GUID is a 42 character hexadecimal string. The GUID is not case sensitive.

Response fields

Parameter	Name	Type
mt_guid	Microcompute Transaction GUID	GUID1	The microcompute transaction under which this log message has been generated.
ex_on	Executed On	datetime2	The date and time on which the MT was executed (in UTC).
cm_on	Completed On	datetime2	The date and time on which the MT completed successfully (in UTC). If the MT did not complete successfully, this field will be null in JSON and empty in XML and HTTP form data.
state	State	integer	The numeric code for the state of the MT.
state_name	State Name	string	The name of the state of the MT.
state_desc	State Description	string	The description of the state of the MT.
sn_host	Service Node Host	string	The host name of the service node from which detailed information can be obtained.

¹ GUID is a 42 character hexadecimal string. The GUID is not case sensitive.

² datetime will be in the form yyyy-MM-dd hh:mm:ss, and will be in UTC.

Information - Service Nodes

This part of the API provides information about the DSUMO infrastructure, details about microcompute transactions, and errors that have occurred while processing microcompute operations. This section deals with the API as it exists on the service nodes. The service node information URL follows this format:

http://[service node host].dsumo.net/info[?f=json|xml]

The service node host name can be obtained from the API calls described above, in the section titled Information - General.

The query string parameter supplied with the url, f=[json|xml] specifies the format of the request. This parameter is optional, however if it is not given then the first character of the HTTP content must be { for JSON or < for XML.

Common request parameters

All calls to the API must include the following two parameters:

Parameter	Name	Type
s_guid	Service GUID	GUID1	This is the GUID provided to you upon creating your DSUMO Computing service. It is used to authenticate API requests.
act	Action	string	The action to be performed: log - Get log messages that were generated while processing microcompute transactions. mo - Get details about a microcompute operation.

¹ GUID is a 42 character hexadecimal string. The GUID is not case sensitive.

All responses from the API will include the following two parameters:

Parameter	Name	Type
s	Status	integer	The status of the API call: 100 - Success
s_c	Readable Status	string	The status of the API call in human-readable format. (These values are for reference only, and should not be relied upon to be consistent).

For each action, additional parameters may be required. Those parameters are described below for each action.

log

The log action will return a list of all log messages generated by microcompute operations in the given time frame. This will include the full log message text and other details not returned by the general information API.

Request parameters

Parameter	Name	Type
types	Log Message Types	commaList1 (optional)	A list of all log message types desired to be returned: caughtException - An exception that was caught by the data container executing the MO. This is equivalent to an unhandled exception in the context of the microcompute function. This is always a fatal error. userThrown - An exception that was caught by code within the microcompute function. The severity of this log message is not rigidly defined by DSUMO and will depend upon the implementation done by the developer. illegalFuncCall - A native JavaScript function which is prohibited by the DSUMO Framework was called by the microcompute function. This is always a fatal error. The default is to return all log message types.
sev	Log Message Severities	commaList1 (optional)	A list of log message severities. Log messages matching any of these severities will be returned: debug - Intended for messages that aid in debugging (this severity will only be logged by microcompute transactions run in the sandbox). info - Informational message. warning - Indicates something is wrong, but there was no failure in execution. error - Indicates a non-fatal failure in execution. fatal - Indicates that the microcompute operation failed at the point that this error was generated, and could not run to completion. The default is to return all log message severities.
start_date	Start Date/Time	datetime2 (optional)	Log messages that were generated on or after this date/time will be returned. Default is zero time (all log messages will be included).
end_date	End Date/Time	datetime2 (optional)	Log messages that were generated on or before this date/time will be returned. Default is the current date/time.
mt_guid	Microcompute Transaction GUID	GUID3 (optional)	Log messages that were generated during this transaction will be returned. Default is no restriction.

¹ commaList is not a data type per se; it is actually a string. However, the API must receive this string as a comma-delimited list in the general form: item1,item2,[..],itemZ

² datetime is not a data type per se; it is actually a string value that represents a date (and optionally a time). The string value will be parsed and will assumed to be in UTC. An offset may be specified if the date/time is not in UTC, by appending a space followed by a plus (+) or minus (-) and then an integer value indicating the UTC offset (e.g. 2012-09-17 22:00:00 -4 would be equivalent to 2012-09-18 02:00:00 UTC). The preferred date/time format is yyyy-MM-dd[ hh:mm:ss]. If a time component is not specified then the time will be assumed to be 00:00:00 (midnight) on the date specified.

³ GUID is a 42 character hexadecimal string. The GUID is not case sensitive.

Response fields

Parameter	Name	Type
mt_g	Microcompute Transaction GUID	GUID1	The microcompute transaction for which this log message has been generated.
mo_g	Microcompute Operation GUID	GUID1	The microcompute operation for which this log message has been generated.
f_n	Microcompute Function Name	string	The microcompute function for which this log message has been generated.
type	Log Message Type	string	The type of log message: caughtException, userThrown, or illegalFuncCall.
sev	Log Message Severity	string	The severity of the log message: debug, info, warning, error or fatal.
dt	Date/time	datetime2	The date and time on which the log message was generated (in UTC).
txt	Log Message Text	string	The text that was logged.

¹ GUID is a 42 character hexadecimal string. The GUID is not case sensitive.

² datetime will be in the form yyyy-MM-dd hh:mm:ss, and will be in UTC.

mo

The mo action is used to retrieve both listed and detailed information about microcompute operations, depending upon the parameters passed.

• If any parameter(s) except mo_guid are set, a list of MOs matching that criteria will be returned.
• If the mo_guid parameter is set, detailed information about that microcompute operation will be returned.

Response fields for both list and detail results are given separately in the following section.

MO details obtained from the service node will include input and output data sets, the function called, any log message(s), and pointers to any related MOs (those created by dfork and dparallel, as well as any that were chained using dreturn).

Remember that microcompute operations are ephemeral and are usually only available for 6 hours following their successful completion, and for 7 days following a termination with unsuccessful completion.

Request parameters

Important: All of the request parameters are listed as optional. However, at least one parameter must be given or the API call will return an error.

Parameter	Name	Type
mo_guid	Microcompute Operation GUID	GUID1 (optional)	Retrieves details about this microcompute operation. If this parameter is given, any additional parameters below are ignored.
mt_guid	Microcompute Transaction GUID	GUID1 (optional)	Retrieves microcompute operations which were created under this transaction.
start_date	Start Date/Time	datetime2 (optional)	Microcompute operations that were created on or after this date/time will be returned. Default is zero time (no limit).
end_date	End Date/Time	datetime2 (optional)	Microcompute operations that were created on or before this date/time will be returned. Default is the current date/time.
state	State	integer (optional)	Microcompute operations that have this state will be returned. Default is all states.
state_name	State Name	string (optional)	Microcompute operations that have this state will be returned. Default is all states. This has the same functionality as state above, but uses the textual representation of the state. If both state and state_name are specified, state_name will be ignored.
func	Function Name	string (optional)	Microcompute operations that were created to execute this microcompute function will be returned. Default is no restriction by function. The function name is case sensitive.

¹ GUID is a 42 character hexadecimal string. The GUID is not case sensitive.

Response (List mode)

The response in list mode (when mo_guid is not specified) will be grouped by mt_guid. The response will follow this hierarchical format:

• Microcompute Transaction 1
  • Microcompute Operation 1-1
  • Microcompute Operation 1-2
  • [...]
  • Microcompute Operation 1-Z
• [...]
• Microcompute Transaction Z
  • Microcompute Operation Z-1
  • Microcompute Operation Z-2
  • [...]
  • Microcompute Operation Z-Z

This is such that every microcompute operation is presented under the microcompute transaction which caused it to be created.

Response fields (List mode)

Parameter	Name	Type
mt_guid	Microcompute Transaction GUID	GUID1	The microcompute transaction under which this MO was created.
mo_guid	Microcompute Operation GUID	GUID1	The GUID of the MO.
func	Microcompute Function Name	string	The microcompute function of the MO.
cr_on	Created On	datetime2	The date/time on which the MO was created.
ex_on	Executed On	datetime2	The date/time on which the MO was executed. This will return null for the JSON format or the empty string for the XML format if the MO was not executed.
cm_on	Completed On	datetime2	The date/time on which the MO was completed. This will return null for the JSON format or the empty string for the XML format if the MO was not executed.
st	State	integer	The numeric code for the state of the MO.
mo_cr_guid	MO Creator GUID	GUID1	The GUID of the microcompute operation which created this microcompute operation (its "parent"). This will return the empty string if this MO was the first MO run in the transaction.
r_t	Return Type	integer	The return type of this MO. Return types indicate the framework call which returned to the server and thus created the MO: 0 - dreturn 1 - dfork 2 - dparallel 3 - dparallelStart
p_gr	Parallel Group	integer	The parallel group of which this MO was a part. Parallel groups are assigned starting at 0 (zero). This field will be set to zero if the MO was not part of any parallel group, or if it was part of the first parallel group. This field is only relevant when return type is 2 or 3.

¹ GUID is a 42 character hexadecimal string. The GUID is not case sensitive.

² datetime will be in the form yyyy-MM-dd hh:mm:ss, and will be in UTC.

Response fields (Detail mode)

Parameter	Name	Type
mt_guid	Microcompute Transaction GUID	GUID1	The microcompute transaction for which this log message has been generated.
mo_guid	Microcompute Operation GUID	GUID1	The microcompute operation for which this log message has been generated.
func	Microcompute Function Name	string	The microcompute function for which this log message has been generated.
cr_on	Created On	datetime2	The date/time on which the MO was created.
ex_on	Executed On	datetime2	The date/time on which the MO was executed. This will return the empty string if the MO was not executed.
cm_on	Completed On	datetime2	The date/time on which the MO was completed. This will return the empty string if the MO was not completed.
st	State	integer	The numeric code for the state of the MO.
parent	MO Parent GUID	GUID1	The GUID of the microcompute operation which created this microcompute operation (its "parent"). This will return the empty string if this MO was the first MO run in the transaction.
r_t	Return Type	integer	The return type of this MO. Return types indicate the framework call which returned to the server and thus created the MO: 0 - dreturn 1 - dfork 2 - dparallel 3 - dparallelStart
p_gr	Parallel Group	integer	The parallel group of which this MO was a part. Parallel groups are assigned starting at 0 (zero). This field will be set to zero if the MO was not part of any parallel group, or if it was part of the first parallel group. This field is only relevant when return type is 2 or 3.
data_in	Data Set In	object3	The data set that was supplied to the microcompute operation.
data_out	Data Set Out	object3	The data set that was returned by the microcompute operation.
child_count	Child Count	integer	The number of MOs created by the current MO. This represents the actual count, irrespective of whether or not the children list below is truncated.
children	Children	varies4	A collection or list of MO GUIDs that represent the MOs created by the current MO. If this list exceeds 100 children, it will be truncated.

¹ GUID is a 42 character hexadecimal string. The GUID is not case sensitive.

² datetime will be in the form yyyy-MM-dd hh:mm:ss, and will be in UTC.

³ The format of the object returned will differ depending upon which request format is used. For JSON, it will be a JSON object that is a sub-object of the response. For the XML format, it will be a JSON string.

⁴ The format of the children returned will differ depending upon which request format is used. For JSON, the child MOs will be given as a JavaScript array. For XML it will be a collection of <child> nodes within the <children> node.