API & PutioSDK
Relevant source files
The following files were used as context for generating this wiki page:
The API & PutioSDK module serves as the central communication layer between the iOS application and the put.io backend services. It abstracts the underlying RESTful API into a Swift-friendly interface, providing unified handling for authentication, data fetching, and error localization.
The system is built around a centralized api instance produced by the PutioSDKFactory. This instance manages the lifecycle of network requests, utilizes custom URL protocols for testing environments, and bridges modern Swift concurrency (async/await) with legacy completion handler patterns used throughout the UIKit codebase.
SDK Initialization and Configuration
The SDK is instantiated via the PutioSDKFactory, which configures the client with necessary metadata such as the Client ID and the device name.
SDK Factory Logic
The factory checks the process environment to determine if it should operate in a production or mocked mode. In debug environments, specifically when PUTIO_E2E_MOCK_API is set to "1", the SDK is configured with an ephemeral URLSession that uses PutioE2EMockURLProtocol to intercept network calls.
Authentication Flow
The application initializes the API token during the AppDelegate lifecycle. It retrieves the token from either the PutioKeychain or an environment variable (PUTIO_E2E_ACCESS_TOKEN) during end-to-end tests.
Sources: Putio/AppDelegate.swift:156-165
Core API Operations
The SDK provides a comprehensive suite of methods for interacting with user data. Most methods follow a pattern of wrapping asynchronous SDK calls into completion blocks that execute on the MainActor.
| Operation Category | Key Methods | Description |
|---|---|---|
| Account | getAccountInfo, getConfig, saveAccountSettings | Manages user profile, disk usage, and app-wide configurations. |
| File Management | getFiles, searchFiles, deleteFiles, renameFile | Core operations for browsing, searching, and modifying the file tree. |
| Transcoding | startMp4Conversion, getMp4ConversionStatus | Handles server-side conversion of video files to MP4 format. |
| Playback | getStartFrom, setStartFrom, getSubtitles | Manages video resumes positions and subtitle track retrieval. |
| Trash & History | listTrash, emptyTrash, getHistoryEvents | Accesses the recycle bin and user activity logs. |
Sources: Putio/Common/API/PutioSDK.swift:39-195
Async/Await to Completion Bridge
The SDK uses a private complete helper to ensure that background tasks are handled correctly and results are dispatched back to the UI thread safely.
Error Localization System
The project implements a robust error localization framework to transform technical PutioSDKError types into human-readable messages and actionable suggestions.
Components
- PutioLocalizedError: A structure containing a message, a recovery suggestion, and the underlying error.
- APIErrorLocalizer: A matcher-based system that pairs specific HTTP status codes or error types with transformation logic.
- PutioErrorLocalizableInput: A protocol that allows various error types to be processed by the localizer.
Common Localizers
| Matcher | Localized Message | Recovery Suggestion |
|---|---|---|
statusCode(0) (Network) | "Network error" | "Please check your internet connection..." |
unknown | "Something went wrong" | "Please try again later" |
statusCode(401) | "Session expired" | "Please sign in again." (Example from tests) |
Sources: Putio/Common/API/PutioSDK+ErrorLocalizer.swift:51-76, PutioTests/APIErrorLocalizerTests.swift:15-32
Testing and Mocking Infrastructure
For automated testing, the system relies on PutioE2EMockURLProtocol. This class intercepts all requests to api.put.io and returns pre-defined JSON fixtures based on the request path and method.
Supported Mock Routes
GET /v2/account/info: Returns mocked user disk usage and settings.GET /v2/files/list: Returns a static list of files including a sample video.GET /v2/files/42/subtitles: Mocks available SRT tracks for a video.POST /v2/files/42/start-from/set: Simulates saving playback position.
Sources: Putio/Common/API/PutioE2EMockURLProtocol.swift:51-78
Summary
The PutioSDK acts as a specialized wrapper around the put.io API, providing the iOS application with a type-safe and thread-safe way to access remote data. By integrating a factory pattern for environment-specific configurations and a comprehensive error localization engine, it ensures that the app remains testable while providing clear feedback to the end-user during failure states. Key responsibilities include managing the transition from asynchronous network code to main-thread UI updates and providing mock data paths for continuous integration and end-to-end testing.