REST APIs in Depth · Advanced Patterns and Consistency
File Uploads and Downloads
Multipart, direct-to-storage uploads, resumable transfers and range requests.
Small files can go through the API as multipart/form-data. For larger files, issue pre-signed URLs so clients upload directly to object storage, then confirm (POST /uploads/{id}:complete). For very large or flaky networks, use resumable uploads (S3 multipart, the tus protocol, or the IETF resumable uploads draft). Downloads should support Range requests (206 Partial Content) for resuming and media seeking, and Content-Disposition for filenames.
Upload strategies
| Criterion | Multipart via API | Pre-signed direct upload | Resumable (multipart/tus) |
|---|---|---|---|
| Max practical size | ~10–50 MB | GBs | Very large / unreliable networks |
| App server load | High | None | None |
| Resume after failure | No | No (single PUT) | Yes |
| Complexity | Low | Medium | Higher |
GET /files/fil_9/content
Range: bytes=1048576-
HTTP/1.1 206 Partial Content
Content-Range: bytes 1048576-5242879/5242880
Accept-Ranges: bytes
Content-Type: video/mp4
Common pitfalls
- Reading whole files into memory on the server.
- Trusting client-declared content types.
- Public buckets instead of short-lived signed URLs.
Key points
- Pre-signed URLs for large files
- Resumable for unreliable networks
- Range requests for downloads
Further reading: tus resumable upload protocol
Practice questions
Why confirm uploads with a separate API call after a pre-signed upload?
Answer
The API can verify the object exists, check size/type, scan it, and atomically link it to the domain record; otherwise orphaned or unverified files accumulate.
What do Range requests enable?
Answer
Resuming interrupted downloads and seeking within media by fetching byte ranges, returning 206 Partial Content.
Open in the app to mark lessons complete, take notes and track your progress.