LogoLogo
User ManualChangelogRoadmapAboutYouTube
Apps
Apps
  • Apps
  • Quick start
  • Detailed reference
    • Manifest
      • Configuration schema
      • Dictionaries
    • Authentication
    • Configuration
    • Event endpoints
    • Synchronization
      • Data flow
      • Synchronization endpoints
      • Synchronization events
      • File download endpoint
    • Design considerations
  • Changelog
    • Changelog
    • Breaking changes
Powered by GitBook
On this page
  • Synchronization endpoints
  • Resource customs
  • Errors handling

Was this helpful?

Export as PDF
  1. Detailed reference
  2. Synchronization

Synchronization endpoints

A place where the synchronization business logic is implemented

PreviousData flowNextSynchronization events

Last updated 3 months ago

Was this helpful?

Synchronization endpoints have a very similar role to message handlers in a message queue system.

They receive the event(message) with data and react to its payload.

There are several endpoints corresponding to events in the Manifest configuration.

Each endpoint receives an appropriate X-APP-TOKEN HTTP header with JWT that allows of the caller.

JWT for all synchronization endpoint requests is extended with an extra context claim synchronization_id.

This claim is a UUID and allows identification of the synchronization process.

Every endpoint should respond with a 2xx HTTP code to be treated as a success.

Synchronization endpoints

All the endpoints follow the semantic [PUT] /consume/{event}.

synchronization.events contains an array of detailed payloads containing actual changes - .

Those events allow retrieving information about what has changed and reacting to that change.

This field for DELETED events is always an empty array.

/consume/attribute_created

subscribed event:

example payload:

{
  "name": "attribute_created",
  "resource_id": {
    "id": "Attribute_code",
    "type": "attribute_code"
  },
  "synchronization": {
    "resource_customs": null,
    "events": []
  }
}

/consume/attribute_updated

/consume/attribute_deleted

example payload:

{
  "name": "attribute_deleted",
  "resource_id": {
    "id": "Attribute_code",
    "type": "attribute_code"
  },
  "synchronization": {
    "resource_customs": {"your": "custom"},
    "events": []
  }
}

/consume/category_created

example payload:

{
  "name": "category_created",
  "resource_id": {
    "id": "Category_code",
    "type": "category_code"
  },
  "synchronization": {
    "resource_customs": null,
    "events": []
  }
}

/consume/category_updated

example payload:

{
  "name": "category_updated",
  "resource_id": {
    "id": "Category_code",
    "type": "category_code"
  },
  "synchronization": {
    "resource_customs": {"your": "custom"},
    "events": []
  }
}

/consume/category_deleted

example payload:

{
  "name": "category_deleted",
  "resource_id": {
    "id": "Category_code",
    "type": "category_code"
  },
  "synchronization": {
    "resource_customs": {"your": "custom"},
    "events": []
  }
}

/consume/product_created

example payload:

{
  "name": "product_created",
  "resource_id": {
    "id": "Product SKU",
    "type": "sku"
  },
  "synchronization": {
    "resource_customs": null,
    "events": []
  }
}

/consume/product_updated

example payload:

{
  "name": "product_updated",
  "resource_id": {
    "id": "Product SKU",
    "type": "sku"
  },
  "synchronization": {
    "resource_customs": {"your": "custom"},
    "events": []
  }
}

/consume/product_deleted

example payload:

{
  "name": "product_updated",
  "resource_id": {
    "id": "Product SKU",
    "type": "sku"
  },
  "synchronization": {
    "resource_customs": {"your": "custom"},
    "events": []
  }
}

/consume/synchronization_started

example payload:

{
    "name": "synchronization_started"
}

/consume/synchronization_ended

example payload:

{
    "name": "synchronization_started"
}

Resource customs

In the above examples, you might have noticed the resource_customs field.

This mechanic allows small pieces of information such as JSON to be stored in the engine.

The most common use case for this would be storing the ID of the eCommerce entity next to the resource. It'll be passed with every following request so it's easier for your business logic to create the requests to the eCommerce system without the need of reaching to the database.

To persist the custom in the response of the endpoint add the following payload

{
  "resource_customs": {
    "id": 1,
    "other_relevent_information": "here"
  }
}

The resource custom will only be persisted on 2xx(non-204) HTTP responses.

Errors handling

Handling of the request payload may fail.

In such case, there are a couple of scenarios:

  • failed connection(including 502 and 503 HTTP errors) - the event will be retried a couple of times before aborting completely

  • 5xx and 3xx HTTP responses

    • for a single resource, the event is not retried as of an internal error and the history entry is marked with a generic message

    • for a synchronization error event is going to be retried eventually leading to the failed synchronization status

  • 4xx HTTP responses

    • for a single resource

      • a custom behavior may be applied via an appropriate response

        {
          "custom_message": "your custom error message",
          "retryable": false
        }

        retryable parameter determines whether the event can be retried. Otherwise, the fail and custom error message will be applied immediately. The message should not exceed the length of 256 chars. If the length is exceeded the message will be truncated.

      • the event is not retried and the history entry is marked with a generic message

    • for a synchronization error event is going to be retried eventually leading to the failed synchronization status

subscribed event:

subscribed event:

subscribed event:

subscribed event:

subscribed event:

subscribed event:

subscribed event:

subscribed event:

subscribed event:

subscribed event:

the full list can be found here
authentication
attribute_created
attribute_updated
attribute_deleted
category_created
category_updated
category_deleted
product_created
product_updated
product_deleted
synchronization_started
synchronization_ended