DataFlux Data Management Real-Time Data Job REST API
Version
This is version 1 of this Representational State Transfer (REST) Application Programming Interface (API).
Overview
The DataFlux Data Management Real-Time Data Job REST API is used to interact with (manage and execute) real-time data services on DataFlux Data Management Server.
This API allows clients to perform the following tasks:
- list, upload, download, update, or delete service job flows on the server
- retrieve inputs and outputs of the metadata of individual service job flows
- execute individual service jobs by passing them input data and receiving back the output data
A real-time service is a job flow that is executed in a real-time service mode, where the request contains input data and the response contains output data. Real-time services are used for very quick job executions, where the client is waiting on the output data on the same connection (so it is more like "near-real-time").
This API is an alternative to the older SOAP API of DataFlux Data Management Server. This REST API is designed to expose this preexisting functionality in a REST-compliant way.
If DataFlux Data Management Server security is enabled, the only authentication mechanism that is supported by the server is HTTP Basic Authentication. This means that every request must include base64-encoded credentials. Depending on your site's security requirements, you can enable the
SSL
option on DataFlux Data Management Server to require that all requests use an encrypted connection. In addition to HTTP Basic Authentication, you can also enable protection against Cross-Site Request Forgery attacks. To learn more, see Cross-Site Request Forgery Protection.
If DataFlux Data Management Server security is enabled, the authorization checks are performed when the specific request is made (not before). This means that a client that requests a list of job flows will see all of the job flows, even those to which the client has no access. This is similar to Windows or UNIX, where you can see all of the files in a directory, even though permissions on some of the files prevent you from accessing them.
The current implementation supports only JSON as a data exchange format. The only exception to this is a job flow content media type, which is an opaque XML document.
Some REST HTTP clients do not send a POST request without a body. Therefore, it is advised to set the body to
{}
when executing a job flow without input data.
The current implementation does not support Conditional PUT for the GET, HEAD, and PUT operations.
Usage Scenario
In a typical usage scenario, the following actions occur:
- A user designs a service job flow in a desktop DataFlux Data Management Studio client.
- The user pushes the service job flow out to DataFlux Data Management Server.
- The service job flow is visible to all REST clients of the server, who can now execute it, potentially making it a part of their business data processing logic.
Executing a service job flow means that REST clients send a request body that contains data to be processed and get a response back with the outputs of the service job flow.
Typically, the input data that goes to a service job flow and the output data that is returned from it consists of macros or declared inputs and outputs, and one or more rows with one or more data fields each.
Base URL
Here is the base URL for real-time data services:
http://www.example.com/SASDataMgmtRTDataJob/rest
Scope
This public API covers real-time data services for the DataFlux Data Management Server. It coexists with the following APIs:
- the DataFlux Data Management Real-Time Process Job REST API, which is used to interact with (manage and execute) real-time process services
- the DataFlux Data Management Batch Job REST API, which is focused on the batch job's execution and administration services
Cross-Site Request Forgery Protection
To protect against Cross-Site Request Forgery attacks, you can configure DataFlux Data Management Server so that all API calls that require authentication must include a valid eTag. The requesting client obtains an eTag from the server by invoking a GET request on the base URL for real-time data services. The root resource is SASDataMgmtRTDataJob/rest. The eTag value that is returned by the server is a hexadecimal string that is generated by a secure hash algorithm. The supplied eTag must be included in the header of all subsequent API calls that require authentication.
An eTag remains valid for 30 minutes. After that time, an error is generated (HTTP 401), and a new eTag is required.
Media Types
Externally-Defined Media Types
The following table lists externally-defined media types. These are standard SAS media types, the description of which can be obtained from your SAS consultant or SAS Technical Support. These media types are not specific to DataFlux real-time data jobs.
Media Type | Description |
---|---|
This media type is used in SAS REST Application Programming Interfaces (APIs) to denote a collection of resources. This media type is part of the SAS REST API standards. |
|
This media type is used in SAS REST APIs to denote a link to a resource. A link is always embedded as an element in a collection of links. Many XML and JSON representations in SAS REST APIs contain a links member which is a collection of links. | |
This media type is the SAS standard representation for an error response from a REST API. |
application/vnd.sas.datamgmt.jobflow.content+xml
The application/vnd.sas.datamgmt.jobflow.content+xml media type is the XML document containing a job flow. A job flow is an XML document and cannot be anything else. This media type is really just an alias for application/xml. It has no link relations or members. It is an opaque XML string with no publicly documented schema. The job flow XML document is generated and manipulated by DataFlux Data Management Studio. It is not manipulated by external clients.
application/vnd.sas.datamgmt.jobflow
The application/vnd.sas.datamgmt.jobflow media type defines a job flow, which is composed of a job flow name string and the job flow XML content. It is used for creating new job flows on the server. It has no link relations. It is just a container for name and content elements.
Member Name | Type | Description |
---|---|---|
version |
integer
|
This media type's schema version number. This representation is version 1. |
name |
string
|
The name of this job flow (including relative path components, if any). A string of up to 4096 bytes in length, which can contain only characters that are valid in a filename under both Windows and UNIX. |
content
|
string
|
A base64-encoded job flow content XML string (application/vnd.sas.datamgmt.jobflow.content+xml) |
JSON Representation Example
{ "version": 1,
"name" : "Event for Logging.djf",
"content" : "PD94bWwgdmVyc2lvbj0iMS4wD4NCiABlPSJTd2UgMTwvdmFsdWU+DQogICAgICA8L3Byb3A+DQogICAgPC9wcm9wc2V0Pg=="
}
application/vnd.sas.datamgmt.jobflow.definition.summary
The application/vnd.sas.datamgmt.jobflow.definition.summary media type defines a summary of a job flow. It is returned as elements of a collection of all available job flows. It supports browse functionality (that is, it shows which job flows are available on the server).
Link Relation | HTTP Method | Description |
---|---|---|
self |
GET
|
Get the definition of a specific job flow, given its ID. URI: Media type: application/vnd.sas.datamgmt.jobflow.definition |
delete
|
DELETE
|
Delete a specific job flow, given its ID. URI: |
Member Name | Type | Description |
---|---|---|
version |
integer
|
This media type's schema version number. This representation is version 1. |
id
|
string
|
The system-assigned unique ID for this object. |
name |
string
|
The name of this job flow. It is provided by the client when issuing a POST request for the content of a new job flow. It cannot be changed. |
description
|
string
|
The description of this job flow. It is an element of the job flow content and cannot be changed. It is returned only if the value is available to the server at the time of the request. |
links
|
array of link objects |
Zero or more link objects. For a description of the link types, see the Link Relations table above. |
JSON Representation Example
{ "version": 1,
"id" : "RXZlbnQgZm9yIExvZ2dpbmcuZGpm",
"description" : "Sample service to log generated events",
"name" : "Event for Logging.djf",
"links": [
{
"href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/jobFlowDefns/RXZlbnQgZm9yIExvZ2dpbmcuZGpm",
"method": "GET",
"rel": "self",
"type": "application/vnd.sas.datamgmt.jobflow.definition+json",
"uri": "/jobFlowDefns/RXZlbnQgZm9yIExvZ2dpbmcuZGpm"
},
{
"href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/jobFlowDefns/RXZlbnQgZm9yIExvZ2dpbmcuZGpm",
"method": "DELETE",
"rel": "delete",
"uri": "/jobFlowDefns/RXZlbnQgZm9yIExvZ2dpbmcuZGpm"
}
]
}
application/vnd.sas.datamgmt.jobflow.definition
The application/vnd.sas.datamgmt.jobflow.definition media type is the full representation of a job flow definition. This media type is used to get the metadata of a job flow, manipulate a job flow, and execute a job flow.
Link Relation | HTTP Method | Description |
---|---|---|
self |
GET
|
Get the definition of the job flow. URI: Media type: application/vnd.sas.datamgmt.jobflow.definition |
delete
|
DELETE
|
Delete the job flow. URI:
|
metadata
|
GET
|
Get the metadata of the job flow (inputs and outputs). URI:
|
content
|
GET
|
Get the contents of the job flow (the XML document). URI: |
updateContent
|
PUT
|
Update the contents of the job flow (the XML document). URI: Media type: application/vnd.sas.datamgmt.jobflow.content+xml |
execute
|
POST
|
Execute the job flow. (Inputs are passed in; outputs are returned.) URI:
Media type: application/vnd.sas.datamgmt.jobflow.metadata |
engines
|
GET
|
Get the collection of application/vnd.sas.datamgmt.engine engines that have this job flow loaded. URI: Media type: application/vnd.sas.collection |
up
|
GET
|
Go back to the list of available job flows. URI:
Media type: application/vnd.sas.collection |
Member Name | Type | Description |
---|---|---|
version |
integer
|
This media type's schema version number. This representation is version 1. |
id
|
string
|
The system-assigned unique ID for this object. |
name |
string
|
The name of this job flow. It is provided by the client when issuing a POST request for a new job flow content. It cannot be changed. |
description
|
string
|
The description of this job flow. It is an element of the job flow content and cannot be changed. It is returned only if the value is available to the server at the time of the request. |
size |
integer
|
The size of this job flow (XML document) in bytes. |
modifiedTimeStamp
|
string
|
Last modification time of this job flow. |
links
|
array of link objects |
Zero or more link objects. For a description of the link types, see the Link Relations table above. |
JSON Representation Example
{ "version": 1,
"id" : "RXZlbnQgZm9yIExvZ2dpbmcuZGpm",
"name" : "Event for Logging.djf",
"description" : "",
"modifiedTimeStamp": "20150106T16:16:37",
"size": 3432,
"links": [
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/jobFlowDefns/RXZlbnQgZm9yIExvZ2dpbmcuZGpm",
"method": "GET",
"rel": "self",
"type": "application/vnd.sas.datamgmt.jobflow.definition+json",
"uri": "/jobFlowDefns/RXZlbnQgZm9yIExvZ2dpbmcuZGpm"
},
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/jobFlowDefns/RXZlbnQgZm9yIExvZ2dpbmcuZGpm",
"method": "DELETE",
"rel": "delete",
"uri": "/jobFlowDefns/RXZlbnQgZm9yIExvZ2dpbmcuZGpm"
},
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/jobFlowDefns/RXZlbnQgZm9yIExvZ2dpbmcuZGpm/metadata",
"method": "GET",
"rel": "metadata",
"type": "application/vnd.sas.datamgmt.jobflow.metadata+json",
"uri": "/jobFlowDefns/RXZlbnQgZm9yIExvZ2dpbmcuZGpm/metadata"
},
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/jobFlowDefns/RXZlbnQgZm9yIExvZ2dpbmcuZGpm/content",
"method": "GET",
"rel": "content",
"type": "application/vnd.sas.datamgmt.jobflow.content+xml",
"uri": "/jobFlowDefns/RXZlbnQgZm9yIExvZ2dpbmcuZGpm/content"
},
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/jobFlowDefns/RXZlbnQgZm9yIExvZ2dpbmcuZGpm/content",
"method": "PUT",
"rel": "updateContent",
"type": "application/vnd.sas.datamgmt.jobflow.content+xml",
"uri": "/jobFlowDefns/RXZlbnQgZm9yIExvZ2dpbmcuZGpm/content"
},
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/jobFlowDefns/RXZlbnQgZm9yIExvZ2dpbmcuZGpm",
"method": "POST",
"rel": "execute",
"type": "application/vnd.sas.datamgmt.jobflow.metadata+json",
"uri": "/jobFlowDefns/RXZlbnQgZm9yIExvZ2dpbmcuZGpm"
},
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/jobFlowDefns/RXZlbnQgZm9yIExvZ2dpbmcuZGpm/engines",
"method": "GET",
"rel": "engines",
"type": "application/vnd.sas.collection+json",
"uri": "/jobFlowDefns/RXZlbnQgZm9yIExvZ2dpbmcuZGpm/engines"
},
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/jobFlowDefns",
"method": "GET",
"rel": "up",
"type": "application/vnd.sas.collection+json",
"uri": "/jobFlowDefns"
}
]
}
application/vnd.sas.datamgmt.jobflow.metadata
The application/vnd.sas.datamgmt.jobflow.metadata media type describes the inputs that the given job flow accepts and the outputs that it can generate. It is also used as a container for the input data that is sent in the execute
request and as a container for the output data that is returned from that request. When the client gets a real-time service job flow metadata representation, it knows how to construct the inputs container for the execute
request and what to expect in the outputs container of the response.
Link Relation | HTTP Method | Description |
---|---|---|
execute |
POST
|
Execute the job flow. (Inputs are passed in; outputs are returned.) URI: Media type: application/vnd.sas.datamgmt.jobflow.metadata |
up
|
GET
|
Go back to the definition of the job flow.
URI: Media type: application/vnd.sas.datamgmt.jobflow.definition |
self
|
GET
|
Refresh this metadata. URI:
Media type: application/vnd.sas.datamgmt.jobflow.metadata |
Member Name | Type | Description |
---|---|---|
version
|
integer
|
This media type's schema version number. This representation is version 1. |
id
|
string
|
The system-assigned unique ID for this object |
name |
string
|
The name of this job flow. It is provided by the client when issuing a POST request for a new job flow content. It cannot be changed. |
description
|
string |
The description of this job flow. It is an element of the job flow content and cannot be changed. |
inputs
|
object
|
This is a set of bindings: an unordered set of zero or more name-value pairs and zero or more data tables. It can be used to construct the The types are defined by DataFlux Data Management Platform (not DataFlux Data Management Server). The data values are converted to strings before they are passed to DataFlux Data Management Platform for job flow execution. The following types are supported:
A data table is a dynamic type that contains two objects. One is metadata, defining an array of names of columns and the type of data stored in each. The other is data, containing an array of rows with columns of data identical to those defined in the metadata. The two objects of a data table are described below:
A data table always has at least one column, and can have zero or more rows. The data values in rows can be null or contain empty strings (for columns of string type). |
outputs
|
object
|
This is a set of bindings: an unordered set of zero or more name-value pairs and zero or more data tables. It can be used to interpret the outputs member of the response from a service data flow execution request. It is valid to have no outputs member in the response (which means the executed service job flow produced no output data). For more information, see the inputs member above. |
links |
array of link objects
|
Zero or more link objects. For a description of the link types, see the Link Relations table above. |
JSON Representation Example
{ "version": 1
"id": "ZGF0YVN2Y1R5cGVzLmRkZg==",
"description": "a data service that exposes all available data types",
"name": "dataSvcTypes.ddf",
"inputs": {
"Process Priority": "low",
"Logging": "disable",
"dataTable": {
"metadata": [
{"name": "Full Name", "type": "string", "maxChars": 255},
{"name": "Age", "type": "integer"},
{"name": "Donor", "type": "boolean"},
{"name": "Birthday", "type": "date"},
{"name": "Temperature", "type": "decimal"}
],
"data": [
["sample string", 2, true, "2014-10-13", 5.5],
["another string", 246, false, "2014-12-31", 15.7075]
]
}
},
"outputs": {
"Address": null,
"RecordsProcessed": "2",
"dataTable": {
"metadata": [
{"name": "status", "type": "string", "maxChars": 15},
{"name": "status code", "type": "integer"}
],
"data": [
["success", 1],
["", null]
]
}
},
"links": [
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/jobFlowDefns/ZGF0YVN2Y1R5cGVzLmRkZg==",
"method": "POST",
"rel": "execute",
"type": "application/vnd.sas.datamgmt.jobflow.metadata+json",
"uri": "jobFlowDefns/ZGF0YVN2Y1R5cGVzLmRkZg=="
},
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/jobFlowDefns/ZGF0YVN2Y1R5cGVzLmRkZg==",
"method": "GET",
"rel": "up",
"type": "application/vnd.sas.datamgmt.jobflow.definition+json",
"uri": "jobFlowDefns/ZGF0YVN2Y1R5cGVzLmRkZg=="
},
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/jobFlowDefns/ZGF0YVN2Y1R5cGVzLmRkZg==/metadata",
"method": "GET",
"rel": "self",
"type": "application/vnd.sas.datamgmt.jobflow.metadata+json",
"uri": "jobFlowDefns/ZGF0YVN2Y1R5cGVzLmRkZg==/metadata"
}
]
}
application/vnd.sas.datamgmt.engine
The application/vnd.sas.datamgmt.engine media type represents an instance of a Data Management Platform Engine that has a job flow loaded. It is returned as elements of a collection of existing engines.
Note: When the collection is not empty, the collection itself contains similar PUT and DELETE links as described below (as well as a rel:up
link to get back to the root context of the API). Those collection-level links apply to the entire collection of engine elements. This allows the client to manage all engines in the collection at once, rather than one at a time.
Link Relation | HTTP Method | Description |
---|---|---|
jobFlow |
GET
|
Get the definition of a specific job flow, given its ID. URI: Media type: application/vnd.sas.datamgmt.jobflow.definition |
self
|
GET
|
Get the collection with this one engine, given its ID. URI: Media type: application/vnd.sas.collection |
delete
|
DELETE
|
Delete the engine, given its ID. URI:
|
updateCompletion
|
PUT
|
Set the URI: Media type: text/plain |
Member Name | Type | Description |
---|---|---|
version
|
integer
|
This media type's schema version number. This representation is version 1. |
id
|
string
|
The system-assigned unique ID for this object. |
jobFlowId
|
string
|
The ID of the job flow loaded into this engine. |
jobFlowName
|
string
|
The name of this job flow. It is provided by the client when issuing a POST request for a new job flow content and it cannot be changed. |
loadTime |
string
|
The date and time stamp of when this engine was instantiated. |
inUseBy |
string
|
The name of the user whose job the engine is executing. If the engine is idle. this member does not show up for the specified engine. |
maxSecondsLeft |
integer
|
The maximum number of seconds this engine is allowed to continue running the job. If the original run job request did not include such a limit, this member does not show up for the specified engine. |
links
|
array of link objects
|
Zero or more link objects. For a description of the link types, see the Link Relations table above. |
JSON Representation Example
{ "version": 1,
"id": 3,
"jobFlowId": "cmFtLmRtYw==",
"jobFlowName": "ram.dmc",
"loadTime": "20141222T15:10:15",
"maxSecondsLeft": 42,
"inUseBy": "sanovo",
"links": [
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/jobFlowDefns/cmFtLmRtYw==",
"method": "GET",
"rel": "jobFlow",
"type": "application/vnd.sas.datamgmt.jobflow.definition+json",
"uri": "/jobFlowDefns/cmFtLmRtYw=="
},
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/engines/3",
"method": "GET",
"rel": "self",
"type": "application/vnd.sas.collection+json",
"uri": "/engines/3"
},
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/engines/3",
"method": "DELETE",
"rel": "delete",
"uri": "/engines/3"
},
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/engines/3/onCompletion",
"method": "PUT",
"rel": "updateCompletion",
"type": "text/plain",
"uri": "/engines/3/onCompletion"
}
]
}
Resources
Summary of Resources
Resource | Methods |
---|---|
/ |
|
/jobFlowDefns
|
|
/jobFlowDefns/{id}
|
|
/serverInfo
|
GET /serverInfo
|
/engines
|
GET /engines
|
Resource /
The /
resource returns a collection of links at the root of this REST API.
GET /
Method | Description |
---|---|
GET / |
Return a collection of top level links. Authentication required: True |
Request:
GET http://www.example.com/SASDataMgmtRTDataJob/rest/
Response: A collection of links, using media type application/json.
{ "links": [
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/jobFlowDefns",
"method": "GET",
"rel": "jobFlowDefns",
"type": "application/vnd.sas.collection+json",
"uri": "/jobFlowDefns"
},
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/jobFlowDefns",
"method": "POST",
"rel": "create",
"type": "application/vnd.sas.datamgmt.jobflow+json",
"uri": "/jobFlowDefns"
},
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/serverInfo",
"method": "GET",
"rel": "serverInfo",
"type": "application/json",
"uri": "/serverInfo"
},
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/engines",
"method": "GET",
"rel": "engines",
"type": "application/vnd.sas.collection+json",
"uri": "/engines"
},
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/engines?name={URL-encoded-name}",
"method": "GET",
"rel": "enginesByName",
"type": "application/vnd.sas.collection+json",
"uri": "/engines?name={URL-encoded-name}"
}
],
"version": 1
}
Resource /jobFlowDefns
The /jobFlowDefns
resource is a collection of summaries of the job flows that are available on the server.
GET /jobFlowDefns
Method | Description |
---|---|
GET /jobFlowDefns |
List the summaries of the job flows that are available on the server. The collection typically contains a small number of items, perhaps up to 25. However, the number of items might be up to 100 in extreme cases. The summary objects themselves are small in terms of the amount of data contained in each one. Therefore, neither pagination nor filtering by job flow name components are supported in the initial version of the API. Authentication required: True |
Request:
GET http://www.example.com/SASDataMgmtRTDataJob/rest/jobFlowDefns
Response: The response will contain a collection of application/vnd.sas.datamgmt.jobflow.definition.summary items.
{ "version": 1
"name": "items",
"count": 2,
"items": [
{ "description": "",
"id": "d2FpdGVyMi5kbWM=",
"name": "waiter2.dmc",
"links": [
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/jobFlowDefns/d2FpdGVyMi5kbWM=",
"method": "GET",
"rel": "self",
"type": "application/vnd.sas.datamgmt.jobflow.definition+json",
"uri": "/jobFlowDefns/d2FpdGVyMi5kbWM="
},
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/jobFlowDefns/d2FpdGVyMi5kbWM=",
"method": "DELETE",
"rel": "delete",
"uri": "/jobFlowDefns/d2FpdGVyMi5kbWM="
}
]
},
{ "description": "",
"id": "d2FpdGVyLmRtYw==",
"name": "waiter.dmc",
"links": [
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/jobFlowDefns/d2FpdGVyLmRtYw==",
"method": "GET",
"rel": "self",
"type": "application/vnd.sas.datamgmt.jobflow.definition+json",
"uri": "/jobFlowDefns/d2FpdGVyLmRtYw=="
},
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/jobFlowDefns/d2FpdGVyLmRtYw==",
"method": "DELETE",
"rel": "delete",
"uri": "/jobFlowDefns/d2FpdGVyLmRtYw=="
}
]
},
],
"links": [
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/",
"method": "GET",
"rel": "up",
"type": "application/vnd.sas.link",
"uri": "/"
}
]
}
HTTP Response Codes: 200, 401, 403, 500
POST /jobFlowDefns
Method | Description |
---|---|
POST /jobFlowDefns |
Create a new job flow on the server with the given name and content using the application/vnd.sas.datamgmt.jobflow media type. Authentication required: True |
Note: DataFlux Data Management Server has no knowledge of the job flow content XML that is passed in and does not validate it. The Data Management Platform Engine runs the job flows that load and interpret that XML. The job flow XML is created by a UI tool such as DataFlux Data Management Studio, which ensures its validity. If an invalid job flow content XML is uploaded, the job flow fails to execute, with a specific error message from the Data Management Platform Engine. This is also true for the PUT request when you are updating an existing job flow with new XML content.
Note: DataFlux Data Management Server requires job flows to have unique names. If a job flow with the same name as the one being posted already exists, DataFlux Data Management Server returns HTTP error 409 .
Note: The job flow name component of the request allows a relative path as part of the job flow name. This causes DataFlux Data Management Server to create the given job flow name under that relative path (creating the path itself along the way, if necessary).
Note: DataFlux Data Management Server controls what characters can be used in a valid job flow name. It is a lowest common denominator of the characters that are valid in filenames on Windows and UNIX platforms. If an invalid character is found, DataFlux Data Management Server returns HTTP error 404. Because the DataFlux Data Management Server controls what characters are allowed in a job flow name, basic URL encoding of the name is sufficient.
Request:
POST http://www.example.com/SASDataMgmtRTDataJob/rest/jobFlowDefns
Response: The response will contain an application/vnd.sas.datamgmt.jobflow.definition item for the newly created job flow.
HTTP Response Codes: 200, 400, 401, 403, 404, 409 , 413, 500
Resource /jobFlowDefns/{id}
The /jobFlowDefns/{id}
resource is of media type application/vnd.sas.datamgmt.jobflow.definition. It allows for manipulation and execution of that specific job flow.
HEAD /jobFlowDefns/{id}
Method | Description |
---|---|
HEAD /jobFlowDefns/{id} |
Check that the job flow exists. Authentication required: True |
Request:
HEAD http://www.example.com/SASDataMgmtRTDataJob/rest/jobFlowDefns/{id}
Response: The response will contain no body.
HTTP Response Codes: 200, 400, 401, 404
GET /jobFlowDefns/{id}/content
Method | Description |
---|---|
GET /jobFlowDefns/{id}/content |
Get contents of the job flow (that is, get the XML document that is the job flow). Authentication required: True |
Authentication required: True
Request:
GET http://www.example.com/SASDataMgmtRTDataJob/rest/jobFlowDefns/{id}/content
Response: The response will contain an XML document (that is, the job flow).
HTTP Response Codes:200, 400, 401, 403, 404, 413, 500
PUT /jobFlowDefns/{id}/content
Method | Description |
---|---|
PUT /jobFlowDefns/{id}/content |
Update contents of a job flow on the server, with the job flow XML passed in the request. Authentication required: True Note: This method changes the contents of a job flow, but not its name. The current version of the DataFlux Data Management Real-Time Data Job REST API does not support a job flow rename operation. To rename a job flow, upload it to DataFlux Data Management Server with a new, unique path name, and delete the old job flow. |
Request:
PUT http://www.example.com/SASDataMgmtRTDataJob/rest/jobFlowDefns/{id}/content
Response: The response will contain an application/vnd.sas.datamgmt.jobflow.definition item for the updated job flow.
HTTP Response Codes: 200, 400, 401, 403, 404, 413, 500
DELETE /jobFlowDefns/{id}
Method | Description |
---|---|
DELETE /jobFlowDefns/{id} |
Delete a job flow from the server. This does not affect jobs that are already running. (They continue running.) Job flows waiting in the queue to run return an HTTP error 404 after they are removed from the queue. Authentication required: True |
Request:
DELETE http://www.example.com/SASDataMgmtRTDataJob/rest/jobFlowDefns/{id}
HTTP Response Codes: 204, 400, 401, 403, 404, 413, 500
GET /jobFlowDefns/{id}/metadata
Method | Description |
---|---|
GET /jobFlowDefns/{id}/metadata |
Get metadata for the job flow. This is implemented as a dedicated request, rather than automatically being included in the application/vnd.sas.datamgmt.jobflow.definition media type. Obtaining metadata can be a very expensive operation (involving starting a child process, loading a job flow, and contacting databases). Therefore, the user must explicitly ask for this information when it is actually needed. Authentication required: True |
Request:
GET http://www.example.com/SASDataMgmtRTDataJob/rest/jobFlowDefns/{id}/metadata
Response: The response will contain an application/vnd.sas.datamgmt.jobflow.metadata item for the job flow.
HTTP Response Codes: 200, 400, 401, 403, 404, 500
GET /jobFlowDefns/{id}/engines
Method | Description |
---|---|
GET /jobFlowDefns/{id}/engines |
Get a collection of application/vnd.sas.datamgmt.engine engines that have the given job flow loaded. Authentication required: True |
Request:
GET http://www.example.com/SASDataMgmtRTDataJob/rest/jobFlowDefns/{id}/engines
Response: The response will contain a collection of application/vnd.sas.datamgmt.engine items. If there are multiple items in the collection, the collection will include separate links to DELETE and to PUT .../onCompletion on the entire collection of engines.
HTTP Response Codes: 200, 400, 401, 403, 404, 500
POST /jobFlowDefns/{id}
Method | Description |
---|---|
POST /jobFlowDefns/{id} |
Execute the job flow, passing it the input data from the request. Authentication required: True |
Request:
POST http://www.example.com/SASDataMgmtRTDataJob/rest/jobFlowDefns/{id}
The Accept
HTTP header of the request must be set to application/vnd.sas.datamgmt.jobflow.metadata+json. Otherwise, HTTP error 400 is returned.
application/vnd.sas.datamgmt.jobflow.metadata+json
{
"inputs": {
"Process Priority": "low",
"Logging": "disable",
"dataTable": {
"metadata": [
{"name": "Full Name", "type": "string", "maxChars": 255},
{"name": "Age", "type": "integer"},
{"name": "Donor", "type": "boolean"},
{"name": "Birthday", "type": "date"},
{"name": "Temperature", "type": "real"}
],
"data": [
["sample string", 2, true, "2014-10-13", 5.5],
["another string", 246, false, "2014-12-31", 15.7075]
]
}
}
}
Response: The response will contain an application/vnd.sas.datamgmt.jobflow.metadata item with the output data from the job flow execution.
application/vnd.sas.datamgmt.jobflow.metadata+json
{
"outputs": {
"Address": null,
"RecordsProcessed": "2",
"dataTable": {
"metadata": [
{"name": "status", "type": "string", "maxChars": 15},
{"name": "status code", "type": "integer"}
],
"data": [
["success", 1],
["", null]
]
}
}
}
HTTP Response Codes:200 , 400 , 401 , 403 , 404 , 500
Resource /serverInfo
The /serverInfo
resource is a summary of select server configuration options and other information.
GET /serverInfo
Method | Description |
---|---|
GET /serverInfo |
List information about the server. Authentication required: True |
Request:
GET http://www.example.com/SASDataMgmtRTDataJob/rest/serverInfo
Response: The response will contain a set of name-value items.
{ "version": 1
"fullProductVersion": "Data Management Server version 2.6",
"fullVersion": "DataFlux Data Management Server version 9.6 (build 118)",
"majorProductVersion": 2,
"minorProductVersion": 6,
"productRevision": 0,
"majorVersion": 9,
"minorVersion": 6,
"buildNumber": 118,
"authenticationConnection": "",
"serverCurrentDate": "20141212T15:58:58",
"serverStartupDate": "20141212T15:29:16",
"minutesFromGmt": -300,
"databaseVersion": [
"Geo/Phone Database --- V3R2 --- 2013-06 --- expires: 3 months"
],
"libraryVersion": [
"Blue Fusion version 8.2 (build 162) --- blufsn82.dll",
"Verify Canada Extension version 1.5 (build 63) --- vcan15.dll",
"Blue Fusion Verify World version 1.5 (build 20) --- addverworld15.dll",
"AddressDoctor 4.1.16.478 --- AD_Validation_C.dll",
"Cluster Engine version 3.7 (build 29) --- ce37.dll"
],
"repositoryInfo": [
{ "name": "VDP_DB2Test_Repository",
"type": "Database",
"uuid": "528F3BF61ACD6E9C",
"version": 8
}
],
"links": [
{ "href": "http://www.sample.com/SASDataMgmtRTDataJob/rest/",
"method": "GET",
"rel": "up",
"type": "application/vnd.sas.collection+json",
"uri": "/"
}
]
}
Resource /engines
The /engines
resource is a collection of instantiated engines.
GET /engines
Method | Description |
---|---|
GET /engines |
Get all instantiated engines. Authentication required: True |
Request:
GET http://www.example.com/SASDataMgmtRTDataJob/rest/engines
Name | Type | Description |
---|---|---|
?name | string |
Get all engines that have the given URL-encoded job flow loaded. Note: This is a query for engines with a specific job flow, not a filter where a partial job flow name can be used. |
Response: The response will contain an application/vnd.sas.collection container with zero or more items of media type application/vnd.sas.datamgmt.engine.