Synchronization endpoints

A place where the synchronization business logic is implemented

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 authentication 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 - the full list can be found here.

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: attribute_created

example payload:

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

/consume/attribute_updated

subscribed event: attribute_updated

/consume/attribute_deleted

subscribed event: attribute_deleted

example payload:

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

/consume/category_created

subscribed event: category_created

example payload:

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

/consume/category_updated

subscribed event: category_updated

example payload:

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

/consume/category_deleted

subscribed event: category_deleted

example payload:

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

/consume/product_created

subscribed event: product_created

example payload:

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

/consume/product_updated

subscribed event: product_updated

example payload:

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

/consume/product_deleted

subscribed event: product_deleted

example payload:

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

/consume/synchronization_started

subscribed event: synchronization_started

example payload:

{
    "name": "synchronization_started"
}

/consume/synchronization_ended

subscribed event: 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