...
Your application may already support native integrations with other existing applications outside the Maestrano platform. Supposing one of your customers starts using Maestrano integration services and connects these 2 applications on the Maestrano platform, records may be replicated inside the 2 applications creating duplicates. To avoid this scenario, all the external IDs coming from the applications ecosystems are exposed so records can be merged.
Importing records
When your application is linked the first time, you should import the existing records from Connec!™. After saving a record locally, the unique ID generated by your application should be returned to Connec!™ so the ID mapping can updated to include your application external ID.
To give a concrete example, let say the list of items is imported from Connec!™ into your application, here is the list of actions that should occur:
Fetch the list of items
| Code Block |
|---|
|
GET https://api-connec.maestrano.com/api/v2/cld-1234/items
Headers
CONNEC-EXTERNAL-IDS: true |
| Code Block |
|---|
| title | Response |
|---|
| collapse | true |
|---|
|
{
"items": [
{
"id": [
{
"realm": "org-abcd",
"provider": "connec",
"id": "c4e505e4-1a38-43f6-9981-4cbe5a7345f3"
}
],
"code": "IT1",
"status": "ACTIVE",
"name": "Steel Claw Hammer",
"created_at": "2016-10-04T00:36:23Z",
"updated_at": "2016-10-04T00:36:23Z",
"group_id": "cld-1234",
"channel_id": "org-abcd",
"resource_type": "items"
}
],
"pagination": {
"skip": 0,
"top": 100,
"total": 1
}
} |
From the list of items fetched, new records will be created in your application generating unique IDs for each of them.
Link back your application external ID
Supposing a new record is created by your application with the ID item-983401, the following request should be sent to Connec!™ to register this external ID
| Code Block |
|---|
|
PUT https://api-connec.maestrano.com/api/v2/cld-1234/items/c4e505e4-1a38-43f6-9981-4cbe5a7345f3
Headers
CONNEC-EXTERNAL-IDS: true
Body
{
"items":
{
"id": [
{
"realm": "unique-account-id",
"provider": "my-application",
"id": "item-983401"
}
]
}
} |
Subsequent requests to fetch this items will return your external ID so you can easily map it back to the existing record within your application.
Creating records
Supposing a user creates an Item or Product inside your application, this record should be sent to Connec!™ so it can be replicated in other application. Let say a new Item is created with the ID item-984502, the following request should be sent
| Code Block |
|---|
|
POST https://api-connec.maestrano.com/api/v2/cld-1234/items
Headers
CONNEC-EXTERNAL-IDS: true
Body:
{
"items": {
"id": [
{
"realm": "unique-account-id",
"provider": "my-application",
"id": "item-984502"
}
],
"name": "Iron Hammer 8oz"
}
} |
| Code Block |
|---|
| title | Response |
|---|
| collapse | true |
|---|
|
{
"items": {
"id": [
{
"realm": "unique-account-id",
"provider": "my-application",
"id": "item-984502"
},
{
"realm": "org-abcd",
"provider": "connec",
"id": "8400ddc0-70ab-0134-fc40-74d43510c326"
}
],
"code": "IT1923",
"status": "ACTIVE",
"name": "Iron Hammer 8oz",
"created_at": "2016-10-10T00:07:54Z",
"updated_at": "2016-10-10T00:07:54Z",
"group_id": "org-fbba",
"channel_id": "org-fbba",
"resource_type": "items"
}
} |
Updating records
Given a record stored in Connec!™ has previously been linked back to your application, you can easily update a record using your application IDs. The request is exactly the same as when creating a record as the record will be matched using your external ID item-984502
| Code Block |
|---|
|
POST https://api-connec.maestrano.com/api/v2/cld-1234/items
Headers
CONNEC-EXTERNAL-IDS: true
Body:
{
"items": {
"id": [
{
"realm": "unique-account-id",
"provider": "my-application",
"id": "item-984502"
}
],
"name": "Steel Hammer 12oz"
}
} |
| Code Block |
|---|
| title | Response |
|---|
| collapse | true |
|---|
|
{
"items": {
"id": [
{
"realm": "unique-account-id",
"provider": "my-application",
"id": "item-984502"
},
{
"realm": "org-abcd",
"provider": "connec",
"id": "8400ddc0-70ab-0134-fc40-74d43510c326"
}
],
"code": "IT1923",
"status": "ACTIVE",
"name": "Steel Hammer 12oz",
"created_at": "2016-10-10T00:07:54Z",
"updated_at": "2016-10-10T00:12:44Z",
"group_id": "org-fbba",
"channel_id": "org-fbba",
"resource_type": "items"
}
} |
API operations
When fetching data from the API, the request header CONNEC-EXTERNAL-IDS can be set to ask Connec!™ to return the known external systems IDs.
...