Decision Insight 20210329 Save PDF Selected topic Selected topic and subtopics All content Mappings Web Services API Learn how to use the mappings Web Services API. Prerequisites Configure mappings Web Services API Simple absorption service This service allows data integrators to inject data into a node using a single mapping. To inject data using one or more mapping in a single transaction, use the full featured service. Usage The mapping is invoked by sending a JSON formatted body via an HTTP request to the URL <node url>/ws/absorb/<space name>/<mapping name> Example of HTTP body { "customerName": "Acme Corp", "category": "Entertainment", "vip": false } URI format All requests must be POST request to the following URL: <node url>/ws/absorb/<space name>/<mapping name>[?options] URI options Name Default value Description wait false Whether or not the call to the Mapping should block until the absorption is complete Examples POST: <node url>/ws/absorb/hvp/Create_Step?wait=true Header format All requests must include three HTTP headers: Header Description Authorization Credentials of the user that wants to execute the mapping.This user must have all the following permissions: "Access data integration API" permission on the node "Access" permission on the space of the mapping "Data Collection" permission on the application with access to the space of the mapping The credentials must be sent using the HTTP Basic authentication scheme (ex: Basic YWRtaW46YWRtaW4= ) Version Version of the API to use. Currently, the only supported value is 1. Content-Type Content type of the request. It must be set to either application/json, text/json or text/plain. Body format The request must contain in the body a JSON object containing the parameters declared for the mapping. { "customerName": "Acme Corp", "vip": false } Parameters must be supplied using the right type. Supplying "false" for a boolean parameter will issue an error. Mapping parameter type JSON data type Example Boolean boolean true Decimal double 123.45 Duration integer with the duration in milliseconds ISO 8601 formatted duration string 1234"PT1849S" Instance UUID string long identifier "dd68f200-8475-11e4-b4a9-0800200c9a66"1487522985861449729 Instant integer with the number of milliseconds since Unix epoch ISO 8601 formatted date string one of the following constants: NOW TODAY YESTERDAY FROM_START UNTIL_END 1418660002223"2014-12-15T16:13:22.223Z" Integer integer 123 String string "Hello" Response format The response is a JSON object containing a single field: the transaction time of the absorbed request. Here is a typical response: HTTP response body { "transactionTime": 1489114438022725600 } Full featured absorption service This service enables data integrators to inject data into a node using one or more mappings in a single transaction. Usage The Mappings are invoked by sending a JSON formatted body via an HTTP request to the URL <node url>/ws/absorb Example of HTTP body [ { "mapping": { "space": "data-integration", "name": "CreateOrUpdate_Customer" }, "parameters": { "customerName": "Acme Corp", "category": "Entertainment", "vip": false } } ] URI format All requests must be POST request to the following URL: <node url>/ws/absorb[?options] URI options Name Default value Description wait false Whether or not the call to the Mapping should block until the absorption is complete Examples POST: <node url>/ws/absorb?wait=true Header format All requests must include the same HTTP headers than expected by the simple absorption service: Authorization, Version and ContentType. All expected headers are described here. Body format The request must contain in the body a JSON encoded list of MappingInput . A MappingInput contains the information to specify a mapping, and the parameters to invoke the specified mapping. Mapping A mapping can be specified via its space & name "mapping": { "space": "data-integration", "name": "CreatePayment" } or via its UUID "mapping": "a130e899-8073-4ee3-b115-bc65ff5321d0" Parameters The parameters to supply are the one specified in the mapping screen in Data integration. "parameters": { "customerName": "Acme Corp", "vip": false } Parameters must be supplied using the right type. Supplying "false" for a boolean parameter will issue an error. All accepted parameter types are described here. Response format The response is a JSON object containing a single field: the transaction time of the absorbed request. Here is a typical response: HTTP response body { "transactionTime": 1489114438022725600 } Examples The following examples use the authorization token Basic YWRtaW46YWRtaW4= which is the uuencoded version of the default credentials of the admin user account (user: admin / password: admin). If you have changed the default credentials of the admin account, you should replace the authorization token with valid uuencoded credentails. Executing a mapping using the simple absorption service and waiting for the absorption to complete Given the following mapping: To absorb a customer using the simple absorption service and wait for the absorption to complete, you need to send the following HTTP request: URL POST: http://localhost:8080/ws/absorb/hvp/CreateOrUpdate_Customer?wait=true HTTP Headers Authorization: Basic YWRtaW46YWRtaW4= Version: 1 Content-Type: application/json HTTP body { "customerName": "Acme Corp", "category": "Entertainment", "vip": true } Executing a mapping with the full-featured service and waiting for the absorption to complete Given the following mapping: To absorb a customer using the web service and wait for the absorption to complete, you need to send the following HTTP request: URL POST: http://localhost:8080/ws/absorb?wait=true HTTP Headers Authorization: Basic YWRtaW46YWRtaW4= Version: 1 Content-Type: application/json HTTP body [ { "mapping": { "name": "CreateOrUpdate_Customer", "space": "hvp" }, "parameters": { "customerName": "Acme Corp", "category": "Entertainment", "vip": true } } ] Executing two mappings in a single request Given the following mappings: Create_Payment & Delete_Payment To create and delete a payment using a single HTTP request, you would send the following request: URL POST: http://localhost:8080/ws/absorb HTTP Headers Authorization: Basic YWRtaW46YWRtaW4= Version: 1 Content-Type: application/json HTTP body [ { "mapping": { "name": "Create_Payment", "space": "hvp" }, "parameters": { "date": "2014-12-12T09:34:22.000", "paymentId": "1234-5678", "amount": 987.30, "emitter": "Acme Bank" } }, { "mapping": { "name": "Delete_Payment", "space": "hvp" }, "parameters": { "date": "2014-12-12T11:02:37.000", "paymentId": "1234-5678" } } ] This is similar to grouping absorptions when invoking the mappings in a route. Absorbing multiple instances in a single request Given the following mapping: To absorb three customers using the web service, you need to send the following HTTP request: URL POST: http://localhost:8080/ws/absorb HTTP Headers Authorization: Basic YWRtaW46YWRtaW4= Version: 1 Content-Type: application/json HTTP body [ { "mapping": { "name": "CreateOrUpdate_Customer", "space": "hvp" }, "parameters": { "customerName": "Acme Corp", "category": "Entertainment", "vip": false } }, { "mapping": { "name": "CreateOrUpdate_Customer", "space": "hvp" }, "parameters": { "customerName": "AmerTek", "category": "Military", "vip": true } }, { "mapping": { "name": "CreateOrUpdate_Customer", "space": "hvp" }, "parameters": { "customerName": "Big Belly Burger", "category": "Restaurants", "vip": false } } ] Related Links
Mappings Web Services API Learn how to use the mappings Web Services API. Prerequisites Configure mappings Web Services API Simple absorption service This service allows data integrators to inject data into a node using a single mapping. To inject data using one or more mapping in a single transaction, use the full featured service. Usage The mapping is invoked by sending a JSON formatted body via an HTTP request to the URL <node url>/ws/absorb/<space name>/<mapping name> Example of HTTP body { "customerName": "Acme Corp", "category": "Entertainment", "vip": false } URI format All requests must be POST request to the following URL: <node url>/ws/absorb/<space name>/<mapping name>[?options] URI options Name Default value Description wait false Whether or not the call to the Mapping should block until the absorption is complete Examples POST: <node url>/ws/absorb/hvp/Create_Step?wait=true Header format All requests must include three HTTP headers: Header Description Authorization Credentials of the user that wants to execute the mapping.This user must have all the following permissions: "Access data integration API" permission on the node "Access" permission on the space of the mapping "Data Collection" permission on the application with access to the space of the mapping The credentials must be sent using the HTTP Basic authentication scheme (ex: Basic YWRtaW46YWRtaW4= ) Version Version of the API to use. Currently, the only supported value is 1. Content-Type Content type of the request. It must be set to either application/json, text/json or text/plain. Body format The request must contain in the body a JSON object containing the parameters declared for the mapping. { "customerName": "Acme Corp", "vip": false } Parameters must be supplied using the right type. Supplying "false" for a boolean parameter will issue an error. Mapping parameter type JSON data type Example Boolean boolean true Decimal double 123.45 Duration integer with the duration in milliseconds ISO 8601 formatted duration string 1234"PT1849S" Instance UUID string long identifier "dd68f200-8475-11e4-b4a9-0800200c9a66"1487522985861449729 Instant integer with the number of milliseconds since Unix epoch ISO 8601 formatted date string one of the following constants: NOW TODAY YESTERDAY FROM_START UNTIL_END 1418660002223"2014-12-15T16:13:22.223Z" Integer integer 123 String string "Hello" Response format The response is a JSON object containing a single field: the transaction time of the absorbed request. Here is a typical response: HTTP response body { "transactionTime": 1489114438022725600 } Full featured absorption service This service enables data integrators to inject data into a node using one or more mappings in a single transaction. Usage The Mappings are invoked by sending a JSON formatted body via an HTTP request to the URL <node url>/ws/absorb Example of HTTP body [ { "mapping": { "space": "data-integration", "name": "CreateOrUpdate_Customer" }, "parameters": { "customerName": "Acme Corp", "category": "Entertainment", "vip": false } } ] URI format All requests must be POST request to the following URL: <node url>/ws/absorb[?options] URI options Name Default value Description wait false Whether or not the call to the Mapping should block until the absorption is complete Examples POST: <node url>/ws/absorb?wait=true Header format All requests must include the same HTTP headers than expected by the simple absorption service: Authorization, Version and ContentType. All expected headers are described here. Body format The request must contain in the body a JSON encoded list of MappingInput . A MappingInput contains the information to specify a mapping, and the parameters to invoke the specified mapping. Mapping A mapping can be specified via its space & name "mapping": { "space": "data-integration", "name": "CreatePayment" } or via its UUID "mapping": "a130e899-8073-4ee3-b115-bc65ff5321d0" Parameters The parameters to supply are the one specified in the mapping screen in Data integration. "parameters": { "customerName": "Acme Corp", "vip": false } Parameters must be supplied using the right type. Supplying "false" for a boolean parameter will issue an error. All accepted parameter types are described here. Response format The response is a JSON object containing a single field: the transaction time of the absorbed request. Here is a typical response: HTTP response body { "transactionTime": 1489114438022725600 } Examples The following examples use the authorization token Basic YWRtaW46YWRtaW4= which is the uuencoded version of the default credentials of the admin user account (user: admin / password: admin). If you have changed the default credentials of the admin account, you should replace the authorization token with valid uuencoded credentails. Executing a mapping using the simple absorption service and waiting for the absorption to complete Given the following mapping: To absorb a customer using the simple absorption service and wait for the absorption to complete, you need to send the following HTTP request: URL POST: http://localhost:8080/ws/absorb/hvp/CreateOrUpdate_Customer?wait=true HTTP Headers Authorization: Basic YWRtaW46YWRtaW4= Version: 1 Content-Type: application/json HTTP body { "customerName": "Acme Corp", "category": "Entertainment", "vip": true } Executing a mapping with the full-featured service and waiting for the absorption to complete Given the following mapping: To absorb a customer using the web service and wait for the absorption to complete, you need to send the following HTTP request: URL POST: http://localhost:8080/ws/absorb?wait=true HTTP Headers Authorization: Basic YWRtaW46YWRtaW4= Version: 1 Content-Type: application/json HTTP body [ { "mapping": { "name": "CreateOrUpdate_Customer", "space": "hvp" }, "parameters": { "customerName": "Acme Corp", "category": "Entertainment", "vip": true } } ] Executing two mappings in a single request Given the following mappings: Create_Payment & Delete_Payment To create and delete a payment using a single HTTP request, you would send the following request: URL POST: http://localhost:8080/ws/absorb HTTP Headers Authorization: Basic YWRtaW46YWRtaW4= Version: 1 Content-Type: application/json HTTP body [ { "mapping": { "name": "Create_Payment", "space": "hvp" }, "parameters": { "date": "2014-12-12T09:34:22.000", "paymentId": "1234-5678", "amount": 987.30, "emitter": "Acme Bank" } }, { "mapping": { "name": "Delete_Payment", "space": "hvp" }, "parameters": { "date": "2014-12-12T11:02:37.000", "paymentId": "1234-5678" } } ] This is similar to grouping absorptions when invoking the mappings in a route. Absorbing multiple instances in a single request Given the following mapping: To absorb three customers using the web service, you need to send the following HTTP request: URL POST: http://localhost:8080/ws/absorb HTTP Headers Authorization: Basic YWRtaW46YWRtaW4= Version: 1 Content-Type: application/json HTTP body [ { "mapping": { "name": "CreateOrUpdate_Customer", "space": "hvp" }, "parameters": { "customerName": "Acme Corp", "category": "Entertainment", "vip": false } }, { "mapping": { "name": "CreateOrUpdate_Customer", "space": "hvp" }, "parameters": { "customerName": "AmerTek", "category": "Military", "vip": true } }, { "mapping": { "name": "CreateOrUpdate_Customer", "space": "hvp" }, "parameters": { "customerName": "Big Belly Burger", "category": "Restaurants", "vip": false } } ]