NotAShelf
7a0a009ced
Signed-off-by: NotAShelf <raf@notashelf.dev> Change-Id: Id0d1f9769b7ccdbf83d5fa78adef62e46a6a6964
412 lines
7.1 KiB
Markdown
412 lines
7.1 KiB
Markdown
# Sync
|
|
|
|
Multi-device library synchronization
|
|
|
|
## Endpoints
|
|
|
|
### POST /api/v1/sync/ack
|
|
|
|
Acknowledge processed changes
|
|
POST /api/sync/ack
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Request Body
|
|
|
|
`Content-Type: application/json`
|
|
|
|
See `docs/api/openapi.json` for the full schema.
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
|--------|-------------|
|
|
| 200 | Changes acknowledged |
|
|
| 400 | Bad request |
|
|
| 401 | Unauthorized |
|
|
|
|
---
|
|
|
|
### GET /api/v1/sync/changes
|
|
|
|
Get changes since cursor
|
|
GET /api/sync/changes
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Parameters
|
|
|
|
| Name | In | Required | Description |
|
|
|------|----|----------|-------------|
|
|
| `cursor` | query | No | Sync cursor |
|
|
| `limit` | query | No | Max changes (max 1000) |
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
|--------|-------------|
|
|
| 200 | Changes since cursor |
|
|
| 400 | Bad request |
|
|
| 401 | Unauthorized |
|
|
|
|
---
|
|
|
|
### GET /api/v1/sync/conflicts
|
|
|
|
List unresolved conflicts
|
|
GET /api/sync/conflicts
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
|--------|-------------|
|
|
| 200 | Unresolved conflicts |
|
|
| 401 | Unauthorized |
|
|
|
|
---
|
|
|
|
### POST /api/v1/sync/conflicts/{id}/resolve
|
|
|
|
Resolve a sync conflict
|
|
POST /api/sync/conflicts/{id}/resolve
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Parameters
|
|
|
|
| Name | In | Required | Description |
|
|
|------|----|----------|-------------|
|
|
| `id` | path | Yes | Conflict ID |
|
|
|
|
#### Request Body
|
|
|
|
`Content-Type: application/json`
|
|
|
|
See `docs/api/openapi.json` for the full schema.
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
|--------|-------------|
|
|
| 200 | Conflict resolved |
|
|
| 400 | Bad request |
|
|
| 401 | Unauthorized |
|
|
|
|
---
|
|
|
|
### GET /api/v1/sync/devices
|
|
|
|
List user's sync devices
|
|
GET /api/sync/devices
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
|--------|-------------|
|
|
| 200 | List of devices |
|
|
| 401 | Unauthorized |
|
|
|
|
---
|
|
|
|
### POST /api/v1/sync/devices
|
|
|
|
Register a new sync device
|
|
POST /api/sync/devices
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Request Body
|
|
|
|
`Content-Type: application/json`
|
|
|
|
See `docs/api/openapi.json` for the full schema.
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
|--------|-------------|
|
|
| 200 | Device registered |
|
|
| 400 | Bad request |
|
|
| 401 | Unauthorized |
|
|
| 500 | Internal server error |
|
|
|
|
---
|
|
|
|
### GET /api/v1/sync/devices/{id}
|
|
|
|
Get device details
|
|
GET /api/sync/devices/{id}
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Parameters
|
|
|
|
| Name | In | Required | Description |
|
|
|------|----|----------|-------------|
|
|
| `id` | path | Yes | Device ID |
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
|--------|-------------|
|
|
| 200 | Device details |
|
|
| 401 | Unauthorized |
|
|
| 403 | Forbidden |
|
|
| 404 | Not found |
|
|
|
|
---
|
|
|
|
### PUT /api/v1/sync/devices/{id}
|
|
|
|
Update a device
|
|
PUT /api/sync/devices/{id}
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Parameters
|
|
|
|
| Name | In | Required | Description |
|
|
|------|----|----------|-------------|
|
|
| `id` | path | Yes | Device ID |
|
|
|
|
#### Request Body
|
|
|
|
`Content-Type: application/json`
|
|
|
|
See `docs/api/openapi.json` for the full schema.
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
|--------|-------------|
|
|
| 200 | Device updated |
|
|
| 401 | Unauthorized |
|
|
| 403 | Forbidden |
|
|
| 404 | Not found |
|
|
|
|
---
|
|
|
|
### DELETE /api/v1/sync/devices/{id}
|
|
|
|
Delete a device
|
|
DELETE /api/sync/devices/{id}
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Parameters
|
|
|
|
| Name | In | Required | Description |
|
|
|------|----|----------|-------------|
|
|
| `id` | path | Yes | Device ID |
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
|--------|-------------|
|
|
| 204 | Device deleted |
|
|
| 401 | Unauthorized |
|
|
| 403 | Forbidden |
|
|
| 404 | Not found |
|
|
|
|
---
|
|
|
|
### POST /api/v1/sync/devices/{id}/token
|
|
|
|
Regenerate device token
|
|
POST /api/sync/devices/{id}/token
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Parameters
|
|
|
|
| Name | In | Required | Description |
|
|
|------|----|----------|-------------|
|
|
| `id` | path | Yes | Device ID |
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
|--------|-------------|
|
|
| 200 | Token regenerated |
|
|
| 401 | Unauthorized |
|
|
| 403 | Forbidden |
|
|
| 404 | Not found |
|
|
|
|
---
|
|
|
|
### GET /api/v1/sync/download/{path}
|
|
|
|
Download a file for sync (supports Range header)
|
|
GET /api/sync/download/{*path}
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Parameters
|
|
|
|
| Name | In | Required | Description |
|
|
|------|----|----------|-------------|
|
|
| `path` | path | Yes | File path |
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
|--------|-------------|
|
|
| 200 | File content |
|
|
| 206 | Partial content |
|
|
| 401 | Unauthorized |
|
|
| 404 | Not found |
|
|
|
|
---
|
|
|
|
### POST /api/v1/sync/report
|
|
|
|
Report local changes from client
|
|
POST /api/sync/report
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Request Body
|
|
|
|
`Content-Type: application/json`
|
|
|
|
See `docs/api/openapi.json` for the full schema.
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
|--------|-------------|
|
|
| 200 | Changes processed |
|
|
| 400 | Bad request |
|
|
| 401 | Unauthorized |
|
|
|
|
---
|
|
|
|
### POST /api/v1/sync/upload
|
|
|
|
Create an upload session for chunked upload
|
|
POST /api/sync/upload
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Request Body
|
|
|
|
`Content-Type: application/json`
|
|
|
|
See `docs/api/openapi.json` for the full schema.
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
|--------|-------------|
|
|
| 200 | Upload session created |
|
|
| 400 | Bad request |
|
|
| 401 | Unauthorized |
|
|
|
|
---
|
|
|
|
### GET /api/v1/sync/upload/{id}
|
|
|
|
Get upload session status
|
|
GET /api/sync/upload/{id}
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Parameters
|
|
|
|
| Name | In | Required | Description |
|
|
|------|----|----------|-------------|
|
|
| `id` | path | Yes | Upload session ID |
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
|--------|-------------|
|
|
| 200 | Upload session status |
|
|
| 401 | Unauthorized |
|
|
| 404 | Not found |
|
|
|
|
---
|
|
|
|
### DELETE /api/v1/sync/upload/{id}
|
|
|
|
Cancel an upload session
|
|
DELETE /api/sync/upload/{id}
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Parameters
|
|
|
|
| Name | In | Required | Description |
|
|
|------|----|----------|-------------|
|
|
| `id` | path | Yes | Upload session ID |
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
|--------|-------------|
|
|
| 204 | Upload cancelled |
|
|
| 401 | Unauthorized |
|
|
| 404 | Not found |
|
|
|
|
---
|
|
|
|
### PUT /api/v1/sync/upload/{id}/chunks/{index}
|
|
|
|
Upload a chunk
|
|
PUT /api/sync/upload/{id}/chunks/{index}
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Parameters
|
|
|
|
| Name | In | Required | Description |
|
|
|------|----|----------|-------------|
|
|
| `id` | path | Yes | Upload session ID |
|
|
| `index` | path | Yes | Chunk index |
|
|
|
|
#### Request Body
|
|
|
|
Chunk binary data
|
|
`Content-Type: application/octet-stream`
|
|
|
|
See `docs/api/openapi.json` for the full schema.
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
|--------|-------------|
|
|
| 200 | Chunk received |
|
|
| 400 | Bad request |
|
|
| 401 | Unauthorized |
|
|
| 404 | Not found |
|
|
|
|
---
|
|
|
|
### POST /api/v1/sync/upload/{id}/complete
|
|
|
|
Complete an upload session
|
|
POST /api/sync/upload/{id}/complete
|
|
|
|
**Authentication:** Required (Bearer JWT)
|
|
|
|
#### Parameters
|
|
|
|
| Name | In | Required | Description |
|
|
|------|----|----------|-------------|
|
|
| `id` | path | Yes | Upload session ID |
|
|
|
|
#### Responses
|
|
|
|
| Status | Description |
|
|
|--------|-------------|
|
|
| 200 | Upload completed |
|
|
| 400 | Bad request |
|
|
| 401 | Unauthorized |
|
|
| 404 | Not found |
|
|
|
|
---
|
|
|