add docs part 2
This commit is contained in:
607
docs/api-reference.md
Normal file
607
docs/api-reference.md
Normal file
@@ -0,0 +1,607 @@
|
||||
# API Reference
|
||||
|
||||
The mobile app communicates with the server through a REST API and WebSocket connection. This document covers all API endpoints used by the app.
|
||||
|
||||
## API Service Structure
|
||||
|
||||
The API is organized into domain-specific sub-APIs:
|
||||
|
||||
| API | Purpose |
|
||||
|-----|---------|
|
||||
| authenticationApi | Login, logout, session management |
|
||||
| usersApi | User profile and settings |
|
||||
| assetsApi | Asset CRUD operations |
|
||||
| albumsApi | Album management |
|
||||
| searchApi | Smart search and filters |
|
||||
| partnersApi | Partner sharing |
|
||||
| sharedLinksApi | External share links |
|
||||
| activitiesApi | Comments and likes |
|
||||
| peopleApi | Face recognition and people |
|
||||
| memoriesApi | Memory lane feature |
|
||||
| trashApi | Trash management |
|
||||
| serverApi | Server info and config |
|
||||
| oauthApi | OAuth authentication |
|
||||
| downloadApi | Asset downloads |
|
||||
| syncApi | Data synchronization |
|
||||
|
||||
## Authentication
|
||||
|
||||
### Login
|
||||
|
||||
```
|
||||
POST /auth/login
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"email": "user@example.com",
|
||||
"password": "password123"
|
||||
}
|
||||
|
||||
Response:
|
||||
{
|
||||
"accessToken": "jwt-token",
|
||||
"userId": "user-uuid",
|
||||
"userEmail": "user@example.com",
|
||||
"name": "John Doe",
|
||||
"isAdmin": false,
|
||||
"profileImagePath": "/path/to/image"
|
||||
}
|
||||
```
|
||||
|
||||
### Logout
|
||||
|
||||
```
|
||||
POST /auth/logout
|
||||
Authorization: Bearer {token}
|
||||
|
||||
Response: 204 No Content
|
||||
```
|
||||
|
||||
### Validate Token
|
||||
|
||||
```
|
||||
POST /auth/validateToken
|
||||
Authorization: Bearer {token}
|
||||
|
||||
Response:
|
||||
{
|
||||
"authStatus": true
|
||||
}
|
||||
```
|
||||
|
||||
### Change Password
|
||||
|
||||
```
|
||||
POST /auth/change-password
|
||||
Authorization: Bearer {token}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"password": "current-password",
|
||||
"newPassword": "new-password"
|
||||
}
|
||||
```
|
||||
|
||||
## OAuth
|
||||
|
||||
### Get OAuth Config
|
||||
|
||||
```
|
||||
GET /oauth/config
|
||||
|
||||
Response:
|
||||
{
|
||||
"enabled": true,
|
||||
"autoRegister": true,
|
||||
"autoLaunch": false,
|
||||
"buttonText": "Login with SSO"
|
||||
}
|
||||
```
|
||||
|
||||
### Start OAuth Flow
|
||||
|
||||
```
|
||||
POST /oauth/authorize
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"redirectUri": "app://oauth-callback",
|
||||
"codeChallenge": "challenge-string",
|
||||
"codeChallengeMethod": "S256"
|
||||
}
|
||||
|
||||
Response:
|
||||
{
|
||||
"url": "https://oauth-provider.com/authorize?..."
|
||||
}
|
||||
```
|
||||
|
||||
### Complete OAuth
|
||||
|
||||
```
|
||||
POST /oauth/callback
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"url": "app://oauth-callback?code=auth-code",
|
||||
"codeVerifier": "verifier-string"
|
||||
}
|
||||
|
||||
Response:
|
||||
{
|
||||
"accessToken": "jwt-token",
|
||||
"userId": "user-uuid",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
## Assets
|
||||
|
||||
### Get All Assets
|
||||
|
||||
```
|
||||
GET /assets?updatedAfter={timestamp}&updatedBefore={timestamp}
|
||||
Authorization: Bearer {token}
|
||||
|
||||
Response:
|
||||
[
|
||||
{
|
||||
"id": "asset-uuid",
|
||||
"ownerId": "user-uuid",
|
||||
"checksum": "sha1-hash",
|
||||
"fileCreatedAt": "2024-01-15T10:30:00Z",
|
||||
"fileModifiedAt": "2024-01-15T10:30:00Z",
|
||||
"type": "IMAGE",
|
||||
"originalFileName": "IMG_1234.jpg",
|
||||
"isFavorite": false,
|
||||
"isArchived": false,
|
||||
"isTrashed": false,
|
||||
"thumbhash": "base64-thumbhash",
|
||||
"exifInfo": { ... }
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Upload Asset
|
||||
|
||||
```
|
||||
POST /assets
|
||||
Authorization: Bearer {token}
|
||||
Content-Type: multipart/form-data
|
||||
|
||||
Form fields:
|
||||
- assetData: File binary
|
||||
- deviceAssetId: Device-specific ID
|
||||
- deviceId: Device identifier
|
||||
- fileCreatedAt: Original creation time
|
||||
- fileModifiedAt: Original modification time
|
||||
- duration: Video duration (if applicable)
|
||||
- isFavorite: Boolean
|
||||
- isArchived: Boolean
|
||||
- isVisible: Boolean
|
||||
|
||||
Response:
|
||||
{
|
||||
"id": "asset-uuid",
|
||||
"duplicate": false
|
||||
}
|
||||
```
|
||||
|
||||
### Get Asset Info
|
||||
|
||||
```
|
||||
GET /assets/{id}
|
||||
Authorization: Bearer {token}
|
||||
|
||||
Response: Asset object
|
||||
```
|
||||
|
||||
### Update Asset
|
||||
|
||||
```
|
||||
PUT /assets/{id}
|
||||
Authorization: Bearer {token}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"isFavorite": true,
|
||||
"isArchived": false,
|
||||
"description": "Updated description"
|
||||
}
|
||||
```
|
||||
|
||||
### Delete Assets
|
||||
|
||||
```
|
||||
DELETE /assets
|
||||
Authorization: Bearer {token}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"ids": ["asset-uuid-1", "asset-uuid-2"],
|
||||
"force": false
|
||||
}
|
||||
```
|
||||
|
||||
### Get Asset Thumbnail
|
||||
|
||||
```
|
||||
GET /assets/{id}/thumbnail?size={thumbnail|preview}
|
||||
Authorization: Bearer {token}
|
||||
|
||||
Response: Image binary
|
||||
```
|
||||
|
||||
### Get Asset Original
|
||||
|
||||
```
|
||||
GET /assets/{id}/original
|
||||
Authorization: Bearer {token}
|
||||
|
||||
Response: Original file binary
|
||||
```
|
||||
|
||||
### Get Video Playback
|
||||
|
||||
```
|
||||
GET /assets/{id}/video/playback
|
||||
Authorization: Bearer {token}
|
||||
|
||||
Response: Video stream
|
||||
```
|
||||
|
||||
### Check Duplicates
|
||||
|
||||
```
|
||||
POST /assets/bulk-upload-check
|
||||
Authorization: Bearer {token}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"assets": [
|
||||
{
|
||||
"id": "device-asset-id",
|
||||
"checksum": "sha1-hash"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
Response:
|
||||
{
|
||||
"results": [
|
||||
{
|
||||
"id": "device-asset-id",
|
||||
"action": "accept|reject",
|
||||
"reason": "duplicate"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Albums
|
||||
|
||||
### Get All Albums
|
||||
|
||||
```
|
||||
GET /albums?shared={true|false}
|
||||
Authorization: Bearer {token}
|
||||
|
||||
Response:
|
||||
[
|
||||
{
|
||||
"id": "album-uuid",
|
||||
"ownerId": "user-uuid",
|
||||
"albumName": "Vacation 2024",
|
||||
"createdAt": "2024-01-15T10:30:00Z",
|
||||
"assetCount": 50,
|
||||
"shared": true,
|
||||
"albumThumbnailAssetId": "asset-uuid"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Create Album
|
||||
|
||||
```
|
||||
POST /albums
|
||||
Authorization: Bearer {token}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"albumName": "New Album",
|
||||
"assetIds": ["asset-uuid-1", "asset-uuid-2"]
|
||||
}
|
||||
|
||||
Response: Album object
|
||||
```
|
||||
|
||||
### Get Album Details
|
||||
|
||||
```
|
||||
GET /albums/{id}
|
||||
Authorization: Bearer {token}
|
||||
|
||||
Response: Album object with assets
|
||||
```
|
||||
|
||||
### Update Album
|
||||
|
||||
```
|
||||
PATCH /albums/{id}
|
||||
Authorization: Bearer {token}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"albumName": "Updated Name",
|
||||
"activityEnabled": true
|
||||
}
|
||||
```
|
||||
|
||||
### Delete Album
|
||||
|
||||
```
|
||||
DELETE /albums/{id}
|
||||
Authorization: Bearer {token}
|
||||
```
|
||||
|
||||
### Add Assets to Album
|
||||
|
||||
```
|
||||
PUT /albums/{id}/assets
|
||||
Authorization: Bearer {token}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"ids": ["asset-uuid-1", "asset-uuid-2"]
|
||||
}
|
||||
```
|
||||
|
||||
### Remove Assets from Album
|
||||
|
||||
```
|
||||
DELETE /albums/{id}/assets
|
||||
Authorization: Bearer {token}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"ids": ["asset-uuid-1", "asset-uuid-2"]
|
||||
}
|
||||
```
|
||||
|
||||
### Add Users to Album
|
||||
|
||||
```
|
||||
PUT /albums/{id}/users
|
||||
Authorization: Bearer {token}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"sharedUserIds": ["user-uuid-1"],
|
||||
"albumUserRoles": [{"userId": "user-uuid-1", "role": "editor"}]
|
||||
}
|
||||
```
|
||||
|
||||
## Search
|
||||
|
||||
### Smart Search
|
||||
|
||||
```
|
||||
POST /search/smart
|
||||
Authorization: Bearer {token}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"query": "beach sunset",
|
||||
"page": 1,
|
||||
"size": 100,
|
||||
"type": "IMAGE"
|
||||
}
|
||||
|
||||
Response:
|
||||
{
|
||||
"assets": {
|
||||
"items": [...],
|
||||
"total": 150,
|
||||
"count": 100
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Metadata Search
|
||||
|
||||
```
|
||||
POST /search/metadata
|
||||
Authorization: Bearer {token}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"originalFileName": "IMG",
|
||||
"city": "New York",
|
||||
"make": "Apple",
|
||||
"takenAfter": "2024-01-01",
|
||||
"takenBefore": "2024-12-31"
|
||||
}
|
||||
```
|
||||
|
||||
### Get Search Suggestions
|
||||
|
||||
```
|
||||
GET /search/suggestions?query={text}&type={type}
|
||||
Authorization: Bearer {token}
|
||||
|
||||
Response:
|
||||
["suggestion1", "suggestion2", ...]
|
||||
```
|
||||
|
||||
## Partners
|
||||
|
||||
### Get Partners
|
||||
|
||||
```
|
||||
GET /partners?direction={shared-by|shared-with}
|
||||
Authorization: Bearer {token}
|
||||
|
||||
Response:
|
||||
[
|
||||
{
|
||||
"id": "user-uuid",
|
||||
"email": "partner@example.com",
|
||||
"name": "Partner Name",
|
||||
"inTimeline": true
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Create Partnership
|
||||
|
||||
```
|
||||
POST /partners/{userId}
|
||||
Authorization: Bearer {token}
|
||||
|
||||
Response: Partner object
|
||||
```
|
||||
|
||||
### Update Partnership
|
||||
|
||||
```
|
||||
PUT /partners/{userId}
|
||||
Authorization: Bearer {token}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"inTimeline": true
|
||||
}
|
||||
```
|
||||
|
||||
### Remove Partnership
|
||||
|
||||
```
|
||||
DELETE /partners/{userId}
|
||||
Authorization: Bearer {token}
|
||||
```
|
||||
|
||||
## Shared Links
|
||||
|
||||
### Create Shared Link
|
||||
|
||||
```
|
||||
POST /shared-links
|
||||
Authorization: Bearer {token}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"type": "ALBUM|INDIVIDUAL",
|
||||
"albumId": "album-uuid",
|
||||
"assetIds": ["asset-uuid"],
|
||||
"allowUpload": false,
|
||||
"allowDownload": true,
|
||||
"showMetadata": true,
|
||||
"password": "optional-password",
|
||||
"expiresAt": "2024-12-31T23:59:59Z"
|
||||
}
|
||||
|
||||
Response:
|
||||
{
|
||||
"id": "link-uuid",
|
||||
"key": "share-key",
|
||||
"url": "https://server/share/share-key"
|
||||
}
|
||||
```
|
||||
|
||||
### Get My Shared Links
|
||||
|
||||
```
|
||||
GET /shared-links/me
|
||||
Authorization: Bearer {token}
|
||||
|
||||
Response: Array of shared links
|
||||
```
|
||||
|
||||
### Delete Shared Link
|
||||
|
||||
```
|
||||
DELETE /shared-links/{id}
|
||||
Authorization: Bearer {token}
|
||||
```
|
||||
|
||||
## Server
|
||||
|
||||
### Get Server Info
|
||||
|
||||
```
|
||||
GET /server/info
|
||||
Authorization: Bearer {token}
|
||||
|
||||
Response:
|
||||
{
|
||||
"version": "1.2.3",
|
||||
"diskAvailable": "50 GB",
|
||||
"diskSize": "100 GB",
|
||||
"diskUsagePercentage": 50
|
||||
}
|
||||
```
|
||||
|
||||
### Get Server Features
|
||||
|
||||
```
|
||||
GET /server/features
|
||||
Authorization: Bearer {token}
|
||||
|
||||
Response:
|
||||
{
|
||||
"clipEncode": true,
|
||||
"facialRecognition": true,
|
||||
"map": true,
|
||||
"trash": true,
|
||||
"oauth": true,
|
||||
"oauthAutoLaunch": false,
|
||||
"passwordLogin": true
|
||||
}
|
||||
```
|
||||
|
||||
### Get Server Config
|
||||
|
||||
```
|
||||
GET /server/config
|
||||
|
||||
Response:
|
||||
{
|
||||
"loginPageMessage": "Welcome",
|
||||
"trashDays": 30,
|
||||
"isInitialized": true
|
||||
}
|
||||
```
|
||||
|
||||
### Ping Server
|
||||
|
||||
```
|
||||
GET /server/ping
|
||||
|
||||
Response:
|
||||
{
|
||||
"res": "pong"
|
||||
}
|
||||
```
|
||||
|
||||
## Error Responses
|
||||
|
||||
All endpoints may return error responses:
|
||||
|
||||
```
|
||||
{
|
||||
"error": "Error Type",
|
||||
"statusCode": 400,
|
||||
"message": "Detailed error message"
|
||||
}
|
||||
```
|
||||
|
||||
Common status codes:
|
||||
- 400: Bad Request
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden
|
||||
- 404: Not Found
|
||||
- 500: Internal Server Error
|
||||
|
||||
---
|
||||
|
||||
[Previous: Data Models](data-models.md) | [Next: Local Storage](local-storage.md)
|
||||
Reference in New Issue
Block a user