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.

  1. POST http://api.dsumo.net/func?f=json HTTP/1.1
  2. Host: api.dusmo.net
  3. Accept: text/html,application/xml,application/json
  4. Connection: keep-alive
  5. Content-Type: application/json; charset=UTF-8
  6. Content-Length: 73
  7.  
  8. { "guid": "000000000000000000000000000000000000000000", "act": "get", "id": 0 }
  1. HTTP/1.1 200 OK
  2. Date: Mon, 01 Jan 2020 21:27:51 GMT
  3. Server: Apache
  4. Content-Length: 114
  5. Connection: close
  6. Content-Type: application/json; charset=UTF-8
  7.  
  8. { "s": 100, "s_c": "OK", "id": 0, "name": "TestFunction", "cmt": "Test comment", "func": "var sHello = \'World\';" }

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.

1 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
  1. POST http://api.dsumo.net/func?f=json HTTP/1.1
  2. Host: api.dusmo.net
  3. Accept: text/html,application/xml,application/json
  4. Connection: keep-alive
  5. Content-Type: application/json; charset=UTF-8
  6. Content-Length: 73
  7.  
  8. { "guid": "000000000000000000000000000000000000000000", "act": "get", "id": 0 }

Sample Response

JSON | XML
  1. HTTP/1.1 200 OK
  2. Date: Mon, 01 Jan 2020 21:27:51 GMT
  3. Server: Apache
  4. Content-Length: 114
  5. Connection: close
  6. Content-Type: application/json; charset=UTF-8
  7.  
  8. { "s": 100, "s_c": "OK", "id": 0, "name": "TestFunction", "cmt": "Test comment", "func": "var sHello = \'World\';" }

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
  1. POST http://api.dsumo.net/func?f=json HTTP/1.1
  2. Host: api.dusmo.net
  3. Accept: text/html,application/xml,application/json
  4. Connection: keep-alive
  5. Content-Type: application/json; charset=UTF-8
  6. Content-Length: 144
  7.  
  8. { "guid": "000000000000000000000000000000000000000000", "act": "add", "name": "TestFunction", "cmt": "Test comment", "func": "var sHello = \'World\';" }

Sample Response

JSON | XML
  1. HTTP/1.1 200 OK
  2. Date: Mon, 01 Jan 2020 21:27:51 GMT
  3. Server: Apache
  4. Content-Length: 34
  5. Connection: close
  6. Content-Type: application/json; charset=UTF-8
  7.  
  8. { "s": 100, "s_c": "OK", "id": 0 }

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
  1. POST http://api.dsumo.net/func?f=json HTTP/1.1
  2. Host: api.dusmo.net
  3. Accept: text/html,application/xml,application/json
  4. Connection: keep-alive
  5. Content-Type: application/json; charset=UTF-8
  6. Content-Length: 156
  7.  
  8. { "guid": "000000000000000000000000000000000000000000", "act": "chg", "id": 0, "name": "TestFunction", "cmt": "Test comment", "func": "var sHello = \'Universe\';" }

Sample Response

JSON | XML
  1. HTTP/1.1 200 OK
  2. Date: Mon, 01 Jan 2020 21:27:51 GMT
  3. Server: Apache
  4. Content-Length: 34
  5. Connection: close
  6. Content-Type: application/json; charset=UTF-8
  7.  
  8. { "s": 100, "s_c": "OK", "id": 0 }

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
  1. POST http://api.dsumo.net/func?f=json HTTP/1.1
  2. Host: api.dusmo.net
  3. Accept: text/html,application/xml,application/json
  4. Connection: keep-alive
  5. Content-Type: application/json; charset=UTF-8
  6. Content-Length: 73
  7.  
  8. { "guid": "000000000000000000000000000000000000000000", "act": "del", "id": 0 }

Sample Response

JSON | XML
  1. HTTP/1.1 200 OK
  2. Date: Mon, 01 Jan 2020 21:27:51 GMT
  3. Server: Apache
  4. Content-Length: 34
  5. Connection: close
  6. Content-Type: application/json; charset=UTF-8
  7.  
  8. { "s": 100, "s_c": "OK", "id": 0 }

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.

1The 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:

  1. <item>a</item><item>b</item><item>c</item>[..]<item>z</item>

Sample Request

JSON | XML
  1. POST http://api.dsumo.net/func?f=json HTTP/1.1
  2. Host: api.dusmo.net
  3. Accept: text/html,application/xml,application/json
  4. Connection: keep-alive
  5. Content-Type: application/json; charset=UTF-8
  6. Content-Length: 64
  7.  
  8. { "guid": "000000000000000000000000000000000000000000", "act": "lst" }

Sample Response

JSON | XML
  1. HTTP/1.1 200 OK
  2. Date: Mon, 01 Jan 2020 21:27:51 GMT
  3. Server: Apache
  4. Content-Length: 65
  5. Connection: close
  6. Content-Type: application/json; charset=UTF-8
  7.  
  8. { "s": 100, "s_c": "OK", "count": 5, "lst": [ 0, 1, 8, 10, 17 ] }

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.

1 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.

1 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.

2 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.

1 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.

1 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.

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

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

3 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.

1 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.

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

2 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.

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

2 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.

1 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.

1 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.

1 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.

1 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).

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

func - Functions.

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).

1 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

2 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.

3 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:

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.

1 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.

1 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.

1 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

2 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.

3 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.

1 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.

1 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.

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

2 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.

1 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.

1 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

2 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.

3 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.

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

2 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.

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.

1 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:

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.

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

2 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.

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

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

3 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.

4 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.