iOS API Documentation

Integration overview

The iOS application uses Firebase Authentication to obtain an ID token, then sends that token to the application server. The server verifies identity and provides approved catalogue data and user-owned account operations.

Endpoint status

Firebase authentication

1. Configure the iOS application with the correct Firebase project and approved sign-in providers.
2. Sign in through the Firebase iOS SDK.
3. Obtain the current Firebase ID token from the signed-in user.
4. Attach it as a bearer token to content and account requests.
5. Refresh through the SDK when necessary; do not permanently cache an ID token.

GET /api/collections/vjs/records?perPage=100 HTTP/1.1
Host: v2.bestmoviesug.com
Authorization: Bearer <FIREBASE_ID_TOKEN>

A Firebase user may exist before an application profile has been created. Call the registration endpoint as part of onboarding, then retrieve the profile.

Registration & profile

Register or resolve existing profile

POST /ios/account/register HTTP/1.1
Host: v2.bestmoviesug.com
Authorization: Bearer <FIREBASE_ID_TOKEN>
Content-Type: application/json

{"name":"Jane"}

Registration uses the verified Firebase UID to find an existing profile. A new profile receives non-privileged defaults. Expected statuses: 200 for an existing profile, 201 for a newly created profile, 400 for invalid input, and 401 for missing or invalid authentication.

Update permitted profile fields

PATCH /ios/account/profile HTTP/1.1
Host: v2.bestmoviesug.com
Authorization: Bearer <FIREBASE_ID_TOKEN>
Content-Type: application/json

{
  "name": "Jane K.",
  "profileImageUrl": "https://example.com/avatar.jpg"
}

Content catalogue

Authenticated iOS clients may retrieve records from the following allowlisted collections. List requests use the same paginated record format; individual record details use the record ID.

GET /api/collections/media/records?page=1&perPage=30
GET /api/collections/media/records/<MEDIA_RECORD_ID>
GET /api/collections/banners/records?page=1&perPage=30

Pagination contract

{
  "page": 1,
  "perPage": 30,
  "totalPages": 4,
  "totalItems": 102,
  "items": [ /* collection records */ ]
}

Begin at page 1 and append items while page < totalPages. Guard against overlapping page requests, provide retry and empty states, and validate each collection's actual JSON fields before finalizing app models.

VJs & genres

The supplied Android CategoriesActivity has two tabs. It loads up to 100 VJs or genres, extracts the name field, sorts names alphabetically and displays a two-column category selector. Selecting an item opens a three-column media grid with 30 records per page and infinite scrolling.

GET /api/collections/media/records?page=1&perPage=30&filter=vjs%20~%20%27VJ%20JUNIOR%27
Authorization: Bearer <FIREBASE_ID_TOKEN>

# Conceptual filter values:
vjs ~ 'VJ JUNIOR'
genres ~ 'Action'

1. Fetch and display the VJ or Genre tab list, sorted by name.
2. When a category is selected, use its name as the filter value, matching Android behavior.
3. Build the filter as a query parameter with URLComponents and URLQueryItem.
4. Escape embedded quotes according to the backend filter syntax; URL encoding alone does not escape filter-language syntax.
5. Load 30 records per page; stop when the last page is reached.
6. Support back navigation, loading, no-results and retry states.

My List · Favorites

POST /ios/account/my-list HTTP/1.1
Authorization: Bearer <FIREBASE_ID_TOKEN>
Content-Type: application/json

{"media":"MEDIA_RECORD_ID"}

The server derives the owner from the authenticated user. Do not include a user field. For deletion, use the favorites collection record ID, not the media record ID. Optimistic UI changes should roll back on failure.

Watch history & progress

POST /ios/account/watch-history HTTP/1.1
Authorization: Bearer <FIREBASE_ID_TOKEN>
Content-Type: application/json

{
  "media": "MEDIA_RECORD_ID",
  "progress": {
    "seasonKey": "1",
    "episodeIndex": 0,
    "timestamp": 120
  },
  "posterUrl": "https://example.com/poster.jpg"
}

The progress object must contain seasonKey (string), episodeIndex (number) and timestamp (seconds). For movies, agree on a consistent season/episode convention and verify it against the live API. Save periodically and when playback pauses or closes.

Playback & entitlement gating

Catalogue responses may contain streaming URLs, but the gateway checks subscription entitlement and can remove playback links for inactive, expired or incomplete subscription states. HTTP 200 does not guarantee that a playable URL is present.

1. Retrieve the selected media record using authenticated catalogue access.
2. Inspect the returned data for an allowed, usable playback URL.
3. If access is unavailable, display the appropriate locked or subscription state.
4. Use AVPlayer for compatible HLS or progressive streams.
5. Test redirects, MIME types, URL expiry, network interruptions and HTTP range support.

Subscription plans & iOS purchases

GET /api/collections/subscription_plans/records
Authorization: Bearer <FIREBASE_ID_TOKEN>

The plan collection is allowlisted for authenticated iOS catalogue requests. It provides plan information for display; it does not mean that an iOS purchase or subscription activation flow is ready.

Required iOS purchase work

1. Configure eligible in-app subscription products in App Store Connect.
2. Implement StoreKit purchase and restore experiences according to applicable App Store rules.
3. Verify transactions on the server before granting or extending streaming entitlement.
4. Handle renewals, cancellations, billing issues, expiry and entitlement restoration.
5. Test sandbox purchases and cross-device entitlement behavior.

Radio, live TV, banners & shorts

Use the same authenticated GET and pagination conventions. Validate production JSON field names, artwork URLs and stream formats before building final data models.

Swift · Firebase + URLSession

This example demonstrates bearer-token acquisition, URL query construction and JSON requests. It is an integration reference, not a complete production networking layer. Define Codable response models only after checking actual API responses.

import Foundation
import FirebaseAuth

enum APIError: Error {
    case notSignedIn
    case invalidURL
    case httpStatus(Int, Data)
}

struct BMUAPIClient {
    private let baseURL = URL(string: "https://v2.bestmoviesug.com")!

    func request(
        _ path: String,
        method: String = "GET",
        query: [URLQueryItem] = [],
        jsonBody: [String: Any]? = nil
    ) async throws -> Data {
        guard let user = Auth.auth().currentUser else {
            throw APIError.notSignedIn
        }

        let token = try await user.getIDToken()
        let cleanPath = path.trimmingCharacters(in: CharacterSet(charactersIn: "/"))
        var parts = URLComponents(
            url: baseURL.appendingPathComponent(cleanPath),
            resolvingAgainstBaseURL: false
        )!
        if !query.isEmpty { parts.queryItems = query }
        guard let url = parts.url else { throw APIError.invalidURL }

        var request = URLRequest(url: url)
        request.httpMethod = method
        request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")

        if let body = jsonBody {
            request.setValue("application/json", forHTTPHeaderField: "Content-Type")
            request.httpBody = try JSONSerialization.data(withJSONObject: body)
        }

        let (data, response) = try await URLSession.shared.data(for: request)
        guard let http = response as? HTTPURLResponse else {
            throw URLError(.badServerResponse)
        }
        guard (200...299).contains(http.statusCode) else {
            throw APIError.httpStatus(http.statusCode, data)
        }
        return data
    }
}

Fetch VJs, genres and filtered media

let api = BMUAPIClient()

let vjData = try await api.request(
    "api/collections/vjs/records",
    query: [URLQueryItem(name: "perPage", value: "100")]
)

let genreData = try await api.request(
    "api/collections/genres/records",
    query: [URLQueryItem(name: "perPage", value: "100")]
)

let mediaData = try await api.request(
    "api/collections/media/records",
    query: [
        URLQueryItem(name: "page", value: "1"),
        URLQueryItem(name: "perPage", value: "30"),
        URLQueryItem(name: "filter", value: "vjs ~ 'VJ JUNIOR'")
    ]
)

// Decode vjData, genreData and mediaData into verified models.

Register, save favorite and update profile

let registration = try await api.request(
    "ios/account/register",
    method: "POST",
    jsonBody: ["name": "Jane"]
)

let favorite = try await api.request(
    "ios/account/my-list",
    method: "POST",
    jsonBody: ["media": "MEDIA_RECORD_ID"]
)

let updatedProfile = try await api.request(
    "ios/account/profile",
    method: "PATCH",
    jsonBody: ["name": "Jane K."]
)

HTTP errors & security rules

• Use Firebase bearer tokens for both catalogue and account requests.
• Do not send gateway secrets, privileged credentials or Android impersonation headers.
• Account ownership is server-derived, never supplied by the client.
• Do not unlock playback from a cached local plan alone.
• Use authenticated GET/HEAD only on approved catalogue collections.
• Do not expose user identifiers, tokens or private account data in logs.

Release checklist

Tick these off as the implementation is verified on real devices. The checkmarks are stored only in this browser.

• Firebase sign-in, token refresh, sign-out and re-login on a physical iPhone.
• Registration 201, existing registration 200 and invalid/no token 401.
• Profile read/update; privileged field updates rejected.
• VJ and Genre lists return real authenticated results and sort correctly.
• VJ JUNIOR and Action filters return expected media; special-character filters tested.
• Media details, series episodes, pagination and search verified against actual JSON.
• My List add/list/remove; watch history create/update/delete.
• Cross-user account access and mutation attempts rejected.
• Free, paid, expired and missing-expiry playback gating checked.
• HLS playback, radio, live TV and foreground/background transitions tested.
• StoreKit purchase, restore, server validation and renewal/expiry lifecycle completed.
• Offline behavior, timeouts, retries, accessibility and App Store review readiness checked.

Implementation notes

Keep the existing Android and website behavior unchanged. Reuse the secure application gateway and account routes, and add server functionality only when testing demonstrates a concrete requirement.