REST API

Overview

Segment Diff Service (SDS) regularly gets a snapshot from Segmentation Service and calculates the diff between the last and the current snapshot.

A client can query snapshots and diffs from SDS. Before querying diffs the client has to initially retrieve a snapshot so that SDS knows that it should track that segment.

Authentication

Each endpoint is secured by Escher. If authentication is invalid (Escher headers are not provided or they are invalid), the following response is returned:

HTTP/1.1 401 Unauthorized
Www-Authenticate: Basic realm="Escher"

The supplied authentication is invalid

Base URLs

Version 2

First, a client has to create the segment in SDS. If the segment already exists in SDS, SDS immediately responds with the latest version of the segment snapshot that it has. If the segment does not yet exist in SDS, it returns 202 Accepted and the client has to retry until SDS returns 200 OK with a snapshot version.

Then the client can retrieve the contact IDs of the segment snapshot by specifying the snapshot version. The client should also store the snapshot version in its own DB so that it knows from which version to get the diff in the future.

After one day (or other sync interval, which can be configured for each segment) the client checks if a new version of the segment snapshot exists. If it does the client gets the diff from the version it stored in its own DB to the current version of the segment snapshot.

Creating segment if it does not exist in SDS

POST /v2/customer/:customerId/segment/:segmentId

Segment does not exist yet

data.lastSegmentRunError is only present when the last segment run failed. sxiResponse contains the unmodified response of SXI.

It can happen data.lastSegmentRunError.excuse is n/a because segmentation does not conform to the documented error format. One can still analyze the segment run in EMSAdmin.

$ http --session=sdsprod POST /v2/customer/210268110/segment/100100819

HTTP/1.1 202 Accepted
Content-Type: application/json

{
    "replyCode": 202,
    "replyText": "Segment is being prepared, try again later.",
    "data": {
        "lastSegmentRunError": {
            "at": "2023-08-09T08:20:14.306794+02:00",
            "excuses": "error 1, error 2",
            "isRecoverable": true,
            "sxiResponse": {...}
        }
    }
}

Segment already exists

$ http --session=sdsprod POST /v2/customer/210268110/segment/100100819

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "version": 0,
        "lastUpdatedAt": "2023-08-01T12:15:38.766576+02:00",
        "lastSegmentRunError": {
            "at": "2023-08-09T08:20:14.306794+02:00",
            "excuses": "error 1, error 2",
            "isRecoverable": true,
            "sxiResponse": {...}
        }
    },
    "replyCode": 200,
    "replyText": "OK"
}

Segment not found

$ http --session=sdsprod POST /v2/customer/210268110/segment/100099693

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "replyCode": 404,
    "replyText": "The segment specified does not exist."
}

Getting snapshot by version

GET /v2/customer/:customerId/segment/:segmentId/versions/:version/contacts/snapshot?lastSeenContactId=…&limit=…

SDS tracks the usage of snapshot versions. A snapshot won’t be cleaned up if it was accessed within the last 30 minutes.

Query Parameters

  • lastSeenContactId - for keyset pagination (optional, default: 0)

    • start at 0, in each following request pass max contact ID from current response

  • limit - number of contact IDs to return in the result (optional, default: 1000, max: 10000)

Segment snapshot exists

$ http --session=sdsprod /v2/customer/210268110/segment/100100819/versions/10/contacts/snapshot lastSeenContactId==0 limit==5

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "contactIds": [
            536767451,
            104090290,
            304059253,
            314150353,
            452524969
        ],
        "version": 10
    },
    "replyCode": 200,
    "replyText": "OK"
}

Segment does not exist

$ http --session=sdsprod /v2/customer/210268110/segment/1001008192/versions/3/contacts/snapshot lastSeenContactId==0 limit==5

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "replyCode": 404,
    "replyText": "Segment 210268110/1001008192 not found"
}

Specified version of segment snapshot does not exist

Segment exists in SDS, but a specified version of the segment snapshot does not exist anymore (only the two latest snapshots of a segment are kept in SDS).

$ http --session=sdsprod /v2/customer/210268110/segment/100100819/versions/3/contacts/snapshot lastSeenContactId==0 limit==5

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "replyCode": 404,
    "replyText": "Segment snapshot 210268110/100100819/3 not found"
}

Get the current version

Checks the SDS database for the current version of the segment. It does not trigger a segment sync in case the segment is not yet available in SDS.

GET v2/customer/:customerId/segment/:segmentId/versions/current

Segment already exists in SDS

lastSegmentRunError is only present when the last segment run failed

$ http --session=sdsprod /v2/customer/210268110/segment/100099692/versions/current

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "segmentId": 100099692,
        "version": 10,
        "lastUpdatedAt": "2023-08-01T12:15:38.766576+02:00",
        "lastSegmentRunError": {
            "at": "2023-08-09T08:20:14.306794+02:00",
            "excuses": "error1",
            "isRecoverable": true,
            "sxiResponse": {...}
        }
    },
    "replyCode": 200,
    "replyText": "OK"
}

Segment does not exist in SDS

$ http --session=sdsprod /v2/customer/210268110/segment/100099699/versions/current

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "replyCode": 404,
    "replyText": "not found"
}

Getting diff between versions

GET v2/customer/:customerId/segment/:segmentId/contacts/diff?fromVersion=…&toVersion=…&lastSeenContactId=…&limit=…

Query Parameters

  • fromVersion - version from which the client wants to get the diff (required)

  • toVersion - version to which the client wants to get the diff (required)

  • lastSeenContactId - for keyset pagination (optional, default: 0)

    • start at 0, in each following request pass max contact ID from current response

  • limit - number of contact IDs to return in the result (optional, default: 1000, max: 10000)

Segment exists in SDS

$ http --session=sdsprod /v2/customer/210268110/segment/100100819/contacts/diff fromVersion==0 toVersion==3 limit==5

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "added": [
            31,
            212,
            276
        ],
        "removed": [
            185,
            340
        ],
        "version": 3
    },
    "replyCode": 200,
    "replyText": "OK"
}

Segment does not exist in SDS

$ http --session=sdsprod /v2/customer/210268110/segment/1001008192/contacts/diff fromVersion==0 toVersion==3 limit==5

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "replyCode": 404,
  "replyText": "Segment not found. Note that segments are removed when they haven't been used for a longer time."
}

Set sync interval

PUT v2/customer/:customerId/segment/:segmentId/sync-interval

Request body

  • Duration encoded as JSON string, e.g. "1 hour" (required, min: "10 minutes", max: "1 day")

    • Examples: "30 minutes", "2 hours", "1 day"

If the sync interval is larger than the one currently set the sync interval is not updated.

Valid duration

$ http --session=sdsprod PUT /v2/customer/210268110/segment/100099692/sync-interval <<< '"10 minutes"'

HTTP/1.1 204 No Content

Invalid duration

$ http --session=sdsprod PUT /v2/customer/210268110/segment/100099692/sync-interval <<< '"1 minute"'

HTTP/1.1 400 Bad Request

Segment not created yet in SDS

or cleaned up by maintenance

$ http --session=sdsprod PUT /v2/customer/210268110/segment/100099692/sync-interval <<< '"1 minute"'

HTTP/1.1 404 Not Found

Count contacts in snapshot by version

was added at 9.9.2021

GET /v2/customer/:customerId/segment/:segmentId/versions/:version/contacts/snapshot/count

Segment snapshot exists

$ http --session=sdsprod /v2/customer/210268110/segment/100100819/versions/10/contacts/snapshot/count

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "count": 123456
    },
    "replyCode": 200,
    "replyText": "OK"
}

Segment does not exist in SDS

$ http --session=sdsprod /v2/customer/210268110/segment/1001008192/versions/3/contacts/snapshot/count

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "replyCode": 404,
    "replyText": "Segment 210268110/1001008192 not found"
}

Specified version of segment snapshot does not exist

Segment exists in SDS, but a specified version of the segment snapshot does not exist anymore (only the two latest snapshots of a segment are kept in SDS).

$ http --session=sdsprod /v2/customer/210268110/segment/100100819/versions/3/contacts/snapshot/count

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "replyCode": 404,
    "replyText": "Segment snapshot 210268110/100100819/3 not found"
}

Resources