Mobile App Integration Guide

API design considerations for iOS and Android clients

Overview

This guide covers best practices for integrating the WAVIC backend API with native mobile applications (iOS and Android).

---

Authentication

Token Storage

Platform	Recommended Storage
iOS	Keychain Services
Android	EncryptedSharedPreferences

Token Refresh Strategy

┌─────────┐       ┌──────────────┐       ┌──────────┐
│  Mobile │◄─────▶│ Access Token │◄─────▶│  API     │
│   App   │       │ (short-lived)│       │ Backend  │
└────┬────┘       └──────────────┘       └──────────┘
     │                    │
     │            ┌───────┴───────┐
     └───────────▶│ Refresh Token │
                  │ (long-lived)  │
                  └───────────────┘

Recommended implementation:

// API returns both tokens
{
  accessToken: "eyJ...",   // 15 min expiry
  refreshToken: "eyJ...",  // 30 day expiry
}

// Silent refresh before expiry
POST /user/refresh-token
Authorization: Bearer <refresh_token>

Biometric Authentication

Enable biometric unlock for token access:

• iOS: Face ID / Touch ID
• Android: BiometricPrompt API

---

API Endpoints for Mobile

Optimized Endpoints

Create mobile-specific endpoints that reduce round trips:

// Single endpoint for dashboard data
GET /mobile/dashboard

Response:
{
  recentSpaces: [...],
  recentTracks: [...],
  notifications: [...],
  storageUsed: { mb: 120, percent: 24 }
}

Pagination

Use cursor-based pagination for infinite scroll:

GET /tracks?cursor=<last_id>&limit=20

Response:
{
  items: [...],
  nextCursor: "507f1f77bcf86cd799439012",
  hasMore: true
}

Response Compression

Enable gzip for all responses:

Request Headers:
Accept-Encoding: gzip

Response Headers:
Content-Encoding: gzip

---

Image Handling

Responsive Images

Return multiple variants:

{
  image: {
    thumbnail: "https://cdn/.../thumb.webp",   // 150x150
    medium: "https://cdn/.../medium.webp",     // 600px
    original: "https://cdn/.../original.webp"  // Full size
  }
}

Image Loading Strategy

Context	Variant	Size
List view	thumbnail	~5 KB
Detail view	medium	~40 KB
Full screen	original	~200 KB

CDN Usage

With Azure CDN configured:

https://sonnance-images.azureedge.net/uploads/...

Benefits:

• Global edge caching
• Reduced latency
• Bandwidth cost savings

---

Offline-First Considerations

Data Caching

Recommend caching layer:

• iOS: Core Data or Realm
• Android: Room or Realm

Sync Strategy

┌─────────────────────────────────────────────────────┐
│                   SYNC FLOW                         │
├─────────────────────────────────────────────────────┤
│                                                     │
│   1. Check connectivity                             │
│   2. Fetch delta (changes since lastSync)          │
│   3. Apply remote changes to local DB              │
│   4. Push local changes to server                  │
│   5. Handle conflicts (last-write-wins / merge)    │
│                                                     │
└─────────────────────────────────────────────────────┘

Delta Sync Endpoint

GET /sync/delta?since=2026-02-01T00:00:00Z

Response:
{
  created: [...],
  updated: [...],
  deleted: ["id1", "id2"],
  serverTime: "2026-02-04T22:00:00Z"
}

---

Push Notifications

Architecture

┌────────────┐    ┌──────────────┐    ┌─────────────┐
│  Backend   │───▶│ Azure        │───▶│ APNs/FCM    │
│  Event     │    │ Notification │    │ (Apple/     │
│            │    │ Hubs         │    │  Google)    │
└────────────┘    └──────────────┘    └─────────────┘
                                             │
                                             ▼
                                      ┌─────────────┐
                                      │   Mobile    │
                                      │    App      │
                                      └─────────────┘

Notification Types

Event	Notification
Track shared	"John shared 'Summer Mix' with you"
Comment added	"New comment on 'Demo v3'"
Collaboration invite	"You're invited to 'Rock Album'"

Device Registration

POST /notifications/register-device
{
  platform: "ios" | "android",
  token: "<push_token>",
  deviceId: "<unique_device_id>"
}

---

Audio Streaming

Streaming Endpoints

// Stream audio with range support
GET /track/:id/stream
Range: bytes=0-1048576

Response:
206 Partial Content
Content-Range: bytes 0-1048576/5000000

Audio Format Recommendations

Format	Use Case	Quality
AAC-HE	Cellular streaming	64-96 kbps
AAC-LC	WiFi streaming	128-256 kbps
FLAC	Download (hi-fi)	Lossless

---

Performance Optimization

Network Optimization

// Batch multiple operations
POST /batch
{
  requests: [
    { method: "GET", path: "/artist/123" },
    { method: "GET", path: "/project/456" },
  ]
}

Connection Pooling

• Keep-Alive connections
• HTTP/2 multiplexing
• Connection reuse

Timeout Configuration

Request Type	Timeout
API calls	30 seconds
Image download	60 seconds
Audio stream	120 seconds
File upload	5 minutes

---

Security for Mobile

Certificate Pinning

Pin the API certificate:

• iOS: URLSessionDelegate
• Android: CertificatePinner (OkHttp)

Device Binding

Optional additional security:

POST /user/login
{
  email: "...",
  password: "...",
  deviceFingerprint: "<unique_device_hash>"
}

Secure Storage Keys

Never store in plaintext:

• Access tokens
• Refresh tokens
• User credentials
• Encryption keys

---

Testing Recommendations

API Testing Tools

• Postman (collection for all endpoints)
• Charles Proxy (request inspection)

Device Testing

• Test on both WiFi and cellular
• Test offline/online transitions
• Test low-memory conditions

---

Last Updated: February 2026