Mappings Web Services API

Learn how to use the 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