Event queue for public app

0. Don’t skip this

A public app needs 2 kind of authentication to use event-queue:

Public app authenticate itself to
- create queues for itself and
- pull events in its queues
Public app get authorization from seller to subscribe to that seller events

1. Create queue

Queue is simple as it sound, it is a first in first out queue that we will put your notification events in one side, and you can periodically pull the events out the other side.

This is how your public app can authenticate as itself. The queue belong to the public app, therefore the public app needs its own token (client_credentials) to create queues. After that use that token to create queue:

POST https://api.tiki.vn/integration/v1/queues
Authorization: Bearer <PUBLIC-APP-SELF-TOKEN>

Request body

{
    "name": "queue 1"
}

Response body

{
    "code": "5a84289f-ed78-4285-9670-9a34508fb4a7",
    "name": "queue 1",
    "status": "ACTIVE"
}

You have many options:

distinct queues for different event types
or a queue for all sellers’ event types

Remember you can always separate to more queues in the future if the workload needed.

Go here for details about the endpoint to create queue.

2. Subscribe to events

After create queues you can free to choose subscriptions which event type to which queue. Currently here is the list of supported event type. We can add more in the near future so keep your eyes on this.

Use the token seller authorized to you to subscribe events on behalf of them:

Example subscription for seller A

Subscribe all ORDER_CREATED_SUCCESSFULLY of SELLER-A to queue 5a84289f-ed78-4285-9670-9a34508fb4a7:

POST https://api.tiki.vn/integration/v1/queues/5a84289f-ed78-4285-9670-9a34508fb4a7/subscriptions
Authorization: Bearer <SELLER-A-TOKEN>

Request body

{
    "event_type": "ORDER_CREATED_SUCCESSFULLY"
}

Response body

{
    "code": "38f9923b-a345-4437-a48a-d5938a4d6182",
    "active": true,
    "event_type": "ORDER_CREATED_SUCCESSFULLY",
    "sid": "969BEA7515A1A27FF4F456C782653F854E6B5D2D"
}

Example subscription for seller B

It’s your design choice to use that same queue for seller B, or a different queue for seller B. In this example, we will subscribe all ORDER_CREATED_SUCCESSFULLY of SELLER-B to that same queue:

POST https://api.tiki.vn/integration/v1/queues/5a84289f-ed78-4285-9670-9a34508fb4a7/subscriptions
Authorization: Bearer <SELLER-B-TOKEN>

Request body

{
    "event_type": "ORDER_CREATED_SUCCESSFULLY"
}

Response body

{
    "code": "abf923b-a345-4437-a48a-d5938a4d6182",
    "active": true,
    "event_type": "ORDER_CREATED_SUCCESSFULLY",
    "sid": "89D7AA7515A1A27FF4F456C782653F854E6B5D2D"
}

You can subscribe multiple event types of multiple sellers into the same queue

After your subscription it will take around 5s for your events if have start routing to your queue. Go here for details about the endpoint to subscribe to events.

3. Pull events

After subscriptions succeed, events will route to your queue if it happened.

3.1. Service level agreement

The event queue system guarantee that it will delivery at least one and in order events

At least one: mean if you have an event this will sure the event will route to your queues. It might delivery duplicate events to you queue but each event generated with a UUID, so you only need to implement a simple idempotent checking to ensure you process each event only one time if you need to.
In order: if multiple events of an object like update price of a product happened it will delivery to your queue as the order those events occurred, so you only need to update with the price of last event and don’t need worry about the order we handle it for you

It’s main api you use in event queue system. After setup queue and subscriptions. You can use this endpoint to periodically pulling and handling events from a queue.

Each time you call this endpoint we will return a list of events (if have) and an ack_id. This ack_id is there for a special purpose. It will help to prevent lost events. In the next pull request you should send the ack_id of previous ack_id so we know you are for sure received events so we will remove them and return you the next events. If you don’t send previous ack_id, you will received old events too. You can also can ack without doing a pull request

The lost events case can happen with many reasons along the network round-trip between our server with your server or your system can crash when handle the events. So even we return events with HTTP 200 to you it will not guarantee you handle them in your system successfully. One case you might lost the event if your pulling service stops for 7 days AND your event list is too big, we might drop event list and stop subscriptions

If you receive an empty event list from a pull call, you better to implement a slowdown mechanism like sleep for 1 minute for the next pull call. It will save unnecessary resources in both your system and our system.

3.2. Pull

POST https://api.tiki.vn/integration/v1/queues/{queueCode}/events/pull
Authorization: Bearer <PUBLIC-APP-SELF-TOKEN>

In your first request

Request body

{
    "ack_id": null
}

Response body

{
    "events": [
      {
          "id": "e4ecb7e5-f12f-4807-ade9-bf4aa1512b71",
          "sid": "063B7B71DF51BDB8B46C00F84F1CA928C30742A7",
          "created_at": 1604388548418,
          "payload": {
                "order_code": "203791555",
                "status": "picking"
          },
          "type": "ORDER_STATUS_UPDATED",
          "version": "v1"
      },
      {
        "id": "a96d8c5b-769e-426a-b051-eaf2a671a596",
        "sid": "063B7B71DF51BDB8B46C00F84F1CA928C30742A7",
        "created_at": 1604388764934,
         "payload": {
                "order_code": "203791555",
                "status": "picking"
          },
        "type": "ORDER_STATUS_UPDATED",
        "version": "v1"
      }
    ],
    "ack_id": "e586abc8-e6f5-43e0-2222-dc24a25c50fv"
}

In your next request

You should use this ack_id to call, then you will get the new events.

Request body

{
  "ack_id": "e586abc8-e6f5-43e0-2222-dc24a25c50fv"
}

Response body

{
  "events": [
      {
        "id": "a96d8c5b-769e-426a-b051-eaf2a671a777",
        "sid": "063B7B71DF51BDB8B46C00F84F1CA928C30742A7",
        "created_at": 1604388764934,
        "payload": {
                "order_code": "203791555",
                "status": "canceled"
          },
        "type": "ORDER_STATUS_UPDATED",
        "version": "v1"
      }
  ],
  "ack_id": "e586abc8-e6f5-43e0-2222-654654223"
}

Go here for details about the endpoint to pull events.

3.3. Acknowledgement

Tell us you have got all events until this point of time. And from the next pull, we only returns events from this point of acknowledgement onward.

POST https://api.tiki.vn/integration/v1/queues/{queueCode}/events/ack
Authorization: Bearer <PUBLIC-APP-SELF-TOKEN>

Request body

{
    "ack_id": "e586abc8-e6f5-43e0-2222-654654223"
}

Go here for details about the endpoint to ack events

Current

0. Don’t skip this

1. Create queue

2. Subscribe to events

Example subscription for seller A

Example subscription for seller B

3. Pull events

3.1. Service level agreement

3.2. Pull

In your first request

In your next request

3.3. Acknowledgement

How can we help?

Leave a Reply Cancel reply