simplefileupload-android/MOBILE.md

Mobile Integration Guide

This document outlines the requirements for mobile applications to integrate with the Simple File Upload Server.

API Endpoints

Upload File

Endpoint: POST /upload
Content-Type: multipart/form-data

Request Parameters:

file: File (required) - The file to upload
max_downloads: Integer (optional) - Maximum number of downloads allowed (default: 1)
expiry_hours: Integer (optional) - Hours until file expires (default: 24, max: 24)

Example Request (Swift):

let url = URL(string: "http://your-server:7777/upload")!
var request = URLRequest(url: url)
request.httpMethod = "POST"

let boundary = "Boundary-\(UUID().uuidString)"
request.setValue("multipart/form-data; boundary=\(boundary)", forHTTPHeaderField: "Content-Type")

var body = Data()
// Add file data
body.append("--\(boundary)\r\n")
body.append("Content-Disposition: form-data; name=\"file\"; filename=\"log.txt\"\r\n")
body.append("Content-Type: text/plain\r\n\r\n")
body.append(fileData)
body.append("\r\n")
// Add parameters
body.append("--\(boundary)\r\n")
body.append("Content-Disposition: form-data; name=\"max_downloads\"\r\n\r\n")
body.append("3\r\n")
body.append("--\(boundary)\r\n")
body.append("Content-Disposition: form-data; name=\"expiry_hours\"\r\n\r\n")
body.append("24\r\n")
body.append("--\(boundary)--\r\n")

request.httpBody = body

Example Request (Kotlin):

val file = File("log.txt")
val requestBody = MultipartBody.Builder()
    .setType(MultipartBody.FORM)
    .addFormDataPart(
        "file",
        file.name,
        file.asRequestBody("application/octet-stream".toMediaType())
    )
    .addFormDataPart("max_downloads", "3")
    .addFormDataPart("expiry_hours", "24")
    .build()

val request = Request.Builder()
    .url("http://your-server:7777/upload")
    .post(requestBody)
    .build()

Success Response:

{
    "code": "ABC123"
}

Error Responses:

{
    "error": "No file part"
}

Status: 400 Bad Request

{
    "error": "No selected file"
}

Status: 400 Bad Request

Download File

Endpoint: GET /download/{code}

Parameters:

• code: 6-character alphanumeric code received from upload

Example Request (Swift):

let code = "ABC123"
let url = URL(string: "http://your-server:7777/download/\(code)")!
let task = URLSession.shared.downloadTask(with: url) { localURL, response, error in
    guard let localURL = localURL else { return }
    // Handle downloaded file
}
task.resume()

Example Request (Kotlin):

val code = "ABC123"
val request = Request.Builder()
    .url("http://your-server:7777/download/$code")
    .get()
    .build()

client.newCall(request).enqueue(object : Callback {
    override fun onResponse(call: Call, response: Response) {
        // Handle downloaded file
    }
    override fun onFailure(call: Call, e: IOException) {
        // Handle error
    }
})

Success Response:

• Status: 200 OK
• Content-Type: application/octet-stream
• Content-Disposition: attachment; filename="original_filename.ext"

Error Responses:

• Status: 404 Not Found
• Content-Type: application/json

Various error messages:

{
    "error": "Invalid or expired code"
}

{
    "error": "File expired"
}

{
    "error": "Download limit reached"
}

{
    "error": "File not found"
}

Implementation Requirements

File Upload

1. Implement proper error handling for network issues
2. Show upload progress to user
3. Handle timeout scenarios (recommended timeout: 60 seconds)
4. Store received code securely if needed
5. Validate file size before upload (max size: 16MB)
6. Implement retry logic for failed uploads

File Download

1. Handle all error scenarios gracefully
2. Show download progress to user
3. Validate downloaded file integrity
4. Implement proper file saving logic
5. Handle interrupted downloads with resume capability if possible

Security Considerations

1. Use HTTPS for all API calls in production
2. Don't store sensitive files for extended periods
3. Implement proper error messages without exposing server details
4. Sanitize all user inputs
5. Handle session timeouts appropriately

Testing Requirements

1. Test with various file types and sizes
2. Verify all error scenarios
3. Test network condition variations:
   • Slow network
   • Intermittent connectivity
   • Network switches (WiFi to Cellular)
4. Test concurrent uploads/downloads
5. Verify proper cleanup of temporary files

Sample Status Codes

• 200: Success
• 400: Bad Request (invalid parameters)
• 404: Not Found (invalid code or expired file)
• 413: Payload Too Large (file size exceeded)
• 500: Server Error

Rate Limiting

• Maximum 10 requests per minute per IP
• Implement exponential backoff for retries

Migration Notes

If upgrading from previous versions:

1. Update API endpoint URLs
2. Implement new error handling
3. Update file size limits
4. Add support for download codes
5. Remove old URL-based download logic