DTS Webservices provide access to DTS Client features by wrapping them in standard REST or SOAP operational protocols.
Connection and Setup
DTS Webservices fully automate the steps the Client uses for connecting to the DTS core modules and setting up for general operation. They are generated with the specific parameters (as configured) hard-coded inside them, thus requiring no initial input from the user.
DTS Webservices are enabled upon deployment, but do not immediately connect to the DTS core modules. Instead, they do so when the first request comes in. This provides more flexibility in deployment and keeps the application server more independent of the DTS core.
Typically, the initial request receives a "500 - Internal Server Error" reply
This error states that the required Endpoint is not ready for use and will persists until the service has completed the initialization procedures and is connected to the respective producer. Subsequent requests will function normally.
During normal operation, this same error signals that the targeted data producer is no longer available and the request cannot be serviced.
Remote Routine Calls
Remote routines (methods, procedures, functions) included in the Webservice will be wrapped as REST or SOAP operations.
REST |
•Each routine can be wrapped as either a GET or POST call using the setting in the UI.
Only STRING and INTEGER types can be query parameters.
•The URL component for invoking the operation is customizable. •Routines returning streams also provide an option to customize the URL component of the Get Records from Stream operation.
|
SOAP |
•Calls will be wrapped as SOAP operations with parameters fed inside a SOAP XML request •The URL for invoking all operations on a service is the same (i.e. the endpoint URL) •The operation name is customizable. •Routines returning streams also provide an option to customize the name of the Get Records from Stream operation. |
See Access for details on URLs and Operation Naming
See Webservice Routine Details Drawer for information on interacting with Remote Routine Calls in the Web UI
Collections and Aggregates
When Collections or Aggregates are included in a Webservice, various operations for requesting records and controlling streams become available.
Aggregates behave exactly like Collections when designing a Webservice
Open Stream with Inline Parameters Opens a persistent stream on a collection based on Query Parameters fed through the URL |
REST |
•GET request •Supports Query Parameters only for fields that are variants of STRING and INTEGER types •Returns a stream_id to be used for record requests •The URL for invoking the operation is customizable |
SOAP |
N/A
|
|
Open Stream with Predicate Opens a persistent stream on a collection based on a Predicate object |
REST |
•POST request •Supports queries on all fields, as well as non-equality and compound queries •The Predicate is expected as a JSON inside the body of the request •Returns a STREAM_ID to be used for record requests •The URL for invoking the operation is customizable |
SOAP |
•Supports queries on all fields, as well as non-equality and compound queries •The Predicate is expected inside the XML SOAP Request •Returns a SOAP XML Response containing the STREAM_ID to be used for record requests •The operation name is customizable
|
|
Get Records from Stream Requests a batch of records from a given stream |
REST |
•GET request •Has two Query Parameters: stream_id and dts__size •Will return dts__size records from the stream identified by stream_id (or however many are left, if less than dts__size ) •The URL for invoking the operation is customizable |
SOAP |
•Expects two parameters in the SOAP REQUEST: stream_id and dts__size •Will return dts__size records from the stream identified by stream_id (or however many are left, if less than dts__size ) •The operation name is customizable
|
|
Stream Has More Queries whether there are more records to get from a given stream |
REST |
•GET request •Has a single Query Parameter: stream_id •Returns true or false •The URL for invoking the method is fixed: [SERVICE_URL]/stream-has-more?stream_id=... |
SOAP |
•Expects a single parameter in the SOAP REQUEST: stream_id •Returns a SOAP response containing true or false for the output value •The operation name is fixed: streamHasMore
|
|
Close Stream Requests the closing of a given stream |
REST |
•GET request •Has a single Query Parameter: stream_id •Returns null •The URL for invoking the method is fixed: [SERVICE_URL]/stream-close?stream_id=... |
SOAP |
•Expects a single parameter in the SOAP REQUEST: stream_id •Returns a SOAP response containing no output •The operation name is fixed: streamClose
|
|
Get Records with Inline Parameters Requests a specific number of records that satisfy the given Query Parameters |
REST |
•GET request •Supports Query Parameters only for fields that are variants of STRING and INTEGER types •Aside from the collection fields, the dts__size Query Parameter is also supported. It specifies how may records should be retrieved. If not included, it defaults to 1. •Returns the requested records •Is equivalent to the following sequence of operations: Open Stream With Inline Parameters -> Get Records From Stream -> Close Stream •The URL for invoking the operation is customizable |
SOAP |
N/A
|
|
Get Records with Predicate Requests a specific number of records that satisfy the given Predicate |
REST |
•POST request •Supports queries on all fields, as well as non-equality and compound queries •The Predicate is expected inside a JSON in the body of the request •Aside from the Predicate, the dts__size field is also supported in the request body. It specifies how may records should be retrieved. If not included, it defaults to 1. •Returns the requested records •Is equivalent to the following sequence of operations: Open Stream With Predicate -> Get Records From Stream -> Close Stream •The URL for invoking the operation is customizable |
SOAP |
•Supports queries on all fields, as well as non-equality and compound queries •The Predicate is expected inside the XML SOAP Request •Aside from the Predicate, the dts__size field is also expected in the SOAP Request. It specifies how may records should be retrieved. If not included, it defaults to 1. •Returns a SOAP XML Response containing the requested records •Is equivalent to the following sequence of operations: Open Stream With Predicate -> Get Records From Stream -> Close Stream •The operation name is customizable
|
|
Get Record for Key Requests a single record that is identified by a given field value (should be a primary key or unique field) |
REST |
•GET request •Supports a single Path Parameter for the Key Field, which must be a variant of STRING and INTEGER types •Returns the requested record •Is equivalent to the following sequence of operations: Open Stream With Inline Parameters (?key_field=...) -> Get Records From Stream (dts__size=1) -> Close Stream •The URL for invoking the operation is customizable |
SOAP |
•Supports a single parameter in the SOAP Request for the Key Field •Returns a SOAP XML Response containing the requested record •Is equivalent to the following sequence of operations: Open Stream With Predicate (eq, key_field) -> Get Records From Stream (dts__size=1) -> Close Stream •The operation name is customizable
|
See Access for details on URLs and Operation Naming
See Webservice Stream Operations Drawer for information on interacting with Remote Routine Calls in the Web UI
Topics
Each topic included in the Webservice will show including/excluding various operations and customizing their accessibility.
Subscribe Subscribes to the topic using the default properties and the group_id provided as a query parameter |
REST |
•GET request •group_id is optional - if absent, a unique one will be generated for this subcription •Returns a stream_id to be used for poll requests •The URL for invoking the operation is customizable •All properties set for the Topic and its Connector are active for the Subscription |
SOAP |
N/A
|
|
Subscribe with Properties Subscribes to the topic using custom properties |
REST |
•POST request •The properties and the group_id are expected in the body of the request in JSON format (they are all optional) •Returns a stream_id to be used for poll requests •The URL for invoking the operation is customizable •The provided Properties will be added to the ones set for the Topic and its Connector and override any with the same key
|
SOAP |
•Supports queries on all fields, as well as non-equality and compound queries •The properties and the group_id are expected inside the XML SOAP Request •Returns a SOAP XML Response containing the stream_id to be used for record requests •The operation name is customizable •The provided Properties will be added to the ones set for the Topic and its Connector and override any with the same key
|
|
Poll Polls a batch of records from a given subscription stream |
REST |
•GET request •Has a single Query Parameter: stream_id •Will return any records available for the subscription identified by stream_id (normally all of them, but a maximum number can be specified during subscription using the properties) •The URL for invoking the operation is customizable |
SOAP |
•Expects a single parameter in the SOAP REQUEST: stream_id •Will return any records available for the subscription identified by stream_id (normally all of them, but a maximum number can be specified during subscription using the properties) •The operation name is customizable
|
|
Close Stream Requests the closing of a given stream |
REST |
•GET request •Has a single Query Parameter: stream_id •Returns null •The URL for invoking the method is fixed: [SERVICE_URL]/stream-close?stream_id=... |
SOAP |
•Expects a single parameter in the SOAP REQUEST: stream_id •Returns a SOAP response containing no output •The operation name is fixed: streamClose
|
|
Push Pushes an entry to the Topic |
REST |
•GET request •Has two query parameters: key and msg •It only supports pushing a single entry onto the topic with the key and message in string format •The URL for invoking the operation is customizable |
SOAP |
•Expects two parameters in the SOAP REQUEST: key and msg •It only supports pushing a single entry onto the topic with the key and message in string format •The operation name is customizable
|
|
Push Many Pushes multiple entries to the topic |
REST |
•POST request •Expects the entries as an array of objects with key and msg attributes in JSON format. For example: [ {"key": "some_key", "msg": "some_msg"}, {"key": "another_key", "msg": "another_msg"} ]
•The URL for invoking the operation is customizable |
SOAP |
•Expects an array of objects (arg0) with key and msg sub-elements in the XML SOAP Request. For example: <soapenv:Body> <ws:pushMany_some_topic> <arg0> <ws:key>some_key</ws:key> <ws:msg>some_msg</ws:msg> </arg0> <arg0> <ws:key>another_key</ws:key> <ws:msg>another_msg</ws:msg> </arg0> </ws:pushMany_some_topic> </soapenv:Body>
•The operation name is customizable
|
See Access for details on URLs and Operation Naming
See Webservice Topic Details Drawer for information on interacting with Topics in the Web UI