Palixo Sync API Specification

Overview

The Palixo Sync API provides a set of endpoints for synchronizing album and picture data between mobile clients and the server. The API supports bidirectional sync with conflict resolution, incremental updates, and efficient image upload/download via presigned URLs.

Key Features

• Pull-based sync: Fetch changes since a specific timestamp
• Push-based mutations: Create, update, upsert, and delete entities
• Pagination: Handle large datasets with continuation tokens
• Idempotency: Safe retry of mutations using idempotency keys
• Presigned URLs: Direct S3 upload/download without Lambda payload limits
• Multi-entity support: Sync albums, pictures, tags, and access control

Base URL

Authentication

All endpoints require authentication using JWT ID tokens from AWS Cognito User Pool.

Cognito Configuration

Using the ID Token

Include the ID Token (not access token) in all API requests:

Authorization: Bearer <JWT_ID_TOKEN>

Token Expiration

• ID Token: Expires in 1 hour (3600 seconds)
• Access Token: Expires in 1 hour (3600 seconds)
• Refresh Token: Expires in 30 days

Common Headers

API Endpoints

{
  "changes": [
    {
      "id": "<ksuid>",
      "v": 1,
      "entityType": "Picture",
      "data": {
        "pictureId": "<ksuid>",
        "albumId": "<albumId>",
        "fileName": "Sunset.jpg",
        "created": "[ksuid]",
        "modified": "[ksuid]"
      }
    }
  ],
  "last_seq": "[ulid]",
  "albums": [
    {
      "albumId": "<albumId>",
      "name": "Vacation 2025",
      "accessLevel": "OWNER"
    }
  ],
  "hasMore": false
}

{
  "albumId": "<albumId>",
  "mutations": [
    {
      "id": "<ksuid>",
      "op": "create",
      "data": {
        "entityType": "Picture",
        "fileName": "Beach.jpg",
        "timestamp": "[ksuid]",
        "created": "[ksuid]"
      }
    }
  ]
}

{
  "uploadUrl": "https://s3.amazonaws.com/bucket/<pictureId>?X-Amz-Algorithm=...",
  "expiresIn": 300
}

{
  "downloadUrl": "https://s3.amazonaws.com/bucket/<pictureId>?X-Amz-Algorithm=...",
  "expiresIn": 300
}

{
  "pictureIds": [
    "<pictureId_1>",
    "<pictureId_2>",
    "<pictureId_3>"
  ]
}

{
  "status": "healthy",
  "service": "sync",
  "timestamp": "2025-11-26T..."
}

Data Types

Entity Types

Picture Entity Fields

KSUID vs ULID

Common Workflows

Initial Sync

1. Call GET /sync/pull without since parameter to fetch all data
2. Process albums array to build local album list
3. Process changes array to populate local database
4. Store last_seq for incremental sync
5. If hasMore is true, repeat with continuationToken

Incremental Sync

1. Call GET /sync/pull?since={last_seq} using stored sequence
2. Process changes array to update local database
3. Update stored last_seq with response value
4. Handle pagination if hasMore is true

Create Picture with Upload

1. Generate unique KSUID for the picture ID (serves as both entity ID and S3 key)
2. Call POST /sync/push to create picture entity
3. Verify successful creation from result
4. Call POST /sync/get-upload-url/:pictureId
5. Upload image to S3 using presigned URL

Error Handling

HTTP Status Codes

Error Response Format

{
  "success": false,
  "message": "Error description",
  "error": "Detailed error message"
}

Client Implementation Notes

This section documents important patterns and considerations for implementing a robust sync client.

Document Processing Order

The client should process entity types in a specific order to satisfy foreign key dependencies:

1. Album - Process first as other entities reference albums
2. Picture - Process second as tags reference pictures
3. PrivateTag - Process third as picture-tags reference tags
4. PrivatePictureTag - Process last as it references both pictures and tags

Duplicate Detection

Server pagination may occasionally return duplicate entities across pages. Clients should track processed entities using a composite key of entityType:id to detect and skip duplicates:

// Pseudocode
seenEntities = Set()
for each change in response.changes:
    key = change.entityType + ":" + change.id
    if key in seenEntities:
        skip  // Duplicate, already processed
    seenEntities.add(key)
    processChange(change)

Pagination Safety

Implement safety limits to prevent infinite loops in case of server pagination bugs:

• Set a maximum page count (e.g., 100 pages)
• Detect if continuation token is unchanged between requests
• Break pagination loop if all entities on a page are duplicates

Push Batching by Album

When pushing mutations, group them by albumId and send separate requests for each album. Push the global album first to ensure user-scoped entities (like tags) are created before album-specific entities that reference them.

Temp ID Replacement

When pushing multiple related mutations in sequence, maintain a mapping of temp IDs to server-assigned IDs. Before sending each batch, scan the mutation data and replace any temp ID references with their real IDs from previous responses:

// Pseudocode
tempIdToRealId = Map()

for each batch in pendingMutations:
    // Replace temp IDs in data fields
    for each mutation in batch:
        for field in ['pictureId', 'privateTagId', 'albumId']:
            if mutation.data[field] in tempIdToRealId:
                mutation.data[field] = tempIdToRealId[mutation.data[field]]

    // Send batch and process results
    response = push(batch)
    for result in response.results:
        if result.temp_id:
            tempIdToRealId[result.temp_id] = result.id

Best Practices