A typical application integration requires to store a mapping your application records IDs with the external application IDs, in this case the Connec!™ IDs.
Connec!™ proposes the option to store third-party systems IDs it integrates with. This can simplifies the integration with Connec!™ as an external application no longer requires to store the mapping of IDs between the 2 systems.
Scenarios
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
GET https://api-connec.maestrano.com/api/v2/cld-1234/items
Headers
CONNEC-EXTERNAL-IDS: 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
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
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"
}
}
{
"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
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"
}
}
{
"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.
Fetch a collection
GET https://api-connec.maestrano.com/api/v2/cld-1234/people
Headers
CONNEC-EXTERNAL-IDS: true
Response
{
"people": [
{
"id": [
{
"realm": "2243",
"provider": "my-external-app",
"id": "1"
},
{
"realm": "org-abcd",
"provider": "connec",
"id": "7fef3180-6bf8-0134-2d52-2f659c5af2a1"
}
],
"code": "PE1",
"status": "ACTIVE",
"title": "Dr.",
"first_name": "Anastasia",
"last_name": "Brekke",
"job_title": "Chief Directives Engineer",
"birth_date": "1985-01-29T00:00:00Z",
"organization_id": [
{
"realm": "2243",
"provider": "my-external-app",
"id": "47"
},
{
"realm": "org-abcd",
"provider": "connec",
"id": "7fe83950-6bf8-0134-2d50-2f659c5af2a1"
}
],
"email": {
"address": "dexter@lakin.com"
},
"created_at": "2016-10-04T00:36:23Z",
"updated_at": "2016-10-04T00:36:23Z",
"group_id": "cld-1234",
"channel_id": "org-abcd",
"resource_type": "people"
},
{
"id": [
{
"realm": "org-abcd",
"provider": "connec",
"id": "7ff80260-6bf8-0134-2d54-2f659c5af2a1"
}
],
"code": "PE2",
"status": "ACTIVE",
"title": "Mrs.",
"first_name": "Gretchen",
"last_name": "Kris",
...
}
],
"pagination": {
"skip": 0,
"top": 100,
"total": 2
}
}
Fetch a single resource
To fetch a single resource using a specific external system ID, the parameters opts[provider] and opts[realm] can be specified.
GET https://api-connec.maestrano.com/api/v2/cld-1234/people/1?opts[provider]=my-external-app&opts[realm]=2243
Headers
CONNEC-EXTERNAL-IDS: true
Response
{
"people": {
"id": [
{
"realm": "2243",
"provider": "my-external-app",
"id": "1"
},
{
"realm": "org-abcd",
"provider": "connec",
"id": "7fef3180-6bf8-0134-2d52-2f659c5af2a1"
}
],
"code": "PE1",
"status": "ACTIVE",
"title": "Dr.",
"first_name": "Anastasia",
"last_name": "Brekke",
"job_title": "Chief Directives Engineer",
"birth_date": "1985-01-29T00:00:00Z",
"organization_id": [
{
"realm": "2243",
"provider": "my-external-app",
"id": "47"
},
{
"realm": "org-abcd",
"provider": "connec",
"id": "7fe83950-6bf8-0134-2d50-2f659c5af2a1"
}
],
"email": {
"address": "dexter@lakin.com"
},
"website": {
"url": "http://schaden.com/urban"
},
"created_at": "2016-10-04T00:36:23Z",
"updated_at": "2016-10-04T00:36:23Z",
"resource_type": "people",
"group_id": "cld-1234",
"channel_id": "org-abcd",
}
}
Create or Update a resource
If any of the specified external_ids is matched, the matching resource will be updated. Otherwise a new resource with these external_ids is created
POST https://api-connec.maestrano.com/api/v2/cld-1234/people
Headers
CONNEC-EXTERNAL-IDS: true
Request:
{
"people": {
"id": [
{
"realm": "2243",
"provider": "my-application",
"id": "17"
}
],
"title": "Mr.",
"first_name": "Bob",
"last_name": "Builder",
"organization_id": [
{
"realm": "2243",
"provider": "my-application",
"id": "4"
}
]
}
}
Response:
{
"people": {
"id": [
{
"realm": "2243",
"provider": "my-application",
"id": "17"
},
{
"realm": "org-abcd",
"provider": "connec",
"id": "8400ddc0-70ab-0134-fc40-74d43510c326"
}
],
"code": "PE136",
"status": "ACTIVE",
"title": "Mr.",
"first_name": "Bob",
"last_name": "Builder",
"organization_id": [
{
"realm": "2243",
"provider": "my-application",
"id": "4"
},
{
"realm": "org-abcd",
"provider": "connec",
"id": "7fe83950-6bf8-0134-2d50-2f659c5af2a1"
}
],
..."created_at": "2016-10-10T00:07:54Z",
"updated_at": "2016-10-10T00:07:54Z",
"group_id": "org-fbba",
"channel_id": "org-fbba",
"resource_type": "people"
}
}