फ़ाइल ट्रांसफर API डिज़ाइन: RESTful सर्वोत्तम प्रथाएँ

Well-designed file transfer REST API पाँच या छह resources expose करता है (sessions, parts, shares, downloads, revocations), HTTP semantics honestly उपयोग करता है (create के लिए POST, idempotent chunks के लिए PUT, revocation के लिए DELETE), और actual byte movement को presigned storage URLs पर push करता है ताकि server कभी bandwidth bottleneck न बने। Authentication TLS 1.3 पर short-lived bearer tokens उपयोग करता है, rate limits creation को metadata reads से differentiate करते हैं, chunked uploads tus resumable pattern या S3 multipart semantics follow करते हैं, और errors RFC 7807 Problem Details follow करते हैं ताकि clients programmatically act कर सकें।

Resource Model को Files के बजाय Actions के आसपास Shape करें

एक common mistake API को file tree के रूप में model करना है। File transfer services तीन resources के रूप में better modeled हैं:

• /sessions — in-flight upload, POST से created, chunk PUTs से populated
• /shares — completed, addressable transfer जिसमें expiry और download budget है
• /downloads — bytes fetch करने के लिए short-lived, signed access handles

Sessions एक complete action के माध्यम से shares बनते हैं; shares time या download budget से expired होते हैं। Revocations share पर PATCH हैं या revocation token से DELETE। "File" या "folder" के लिए कोई nouns नहीं — ये storage के implementation details हैं, आपका public contract नहीं।

यह shape API surface small (10 endpoints से कम) रखता है, HTTP caching पर cleanly map करता है (shares Cache-Control: private, max-age=60; downloads no-store), और clients break किए बिना storage backends swap करने देता है।

Authentication और Authorization Patterns

User-facing APIs के लिए, EdDSA से signed short-lived JWTs (15-minute TTL) issue करें, और secure HttpOnly cookie के माध्यम से refresh करें। Token को Authorization: Bearer में रखें, query strings में कभी नहीं जहाँ यह logged हो।

Machine-to-machine के लिए, HMAC-SHA256 request signing bearer tokens से better है क्योंकि यह key send किए बिना key का possession prove करता है। AWS SigV4 reference design है:

Authorization: HEX4-HMAC-SHA256 
  Credential=AKIA.../20261202/eu/transfer/hex4_request,
  SignedHeaders=host;x-hex-date;x-hex-content-sha256,
  Signature=...

Presigned download URLs के लिए, TTLs minutes होने चाहिए, hours नहीं। 15-minute window usability और leaked URL forwarded होने के risk के बीच balance करता है। IP lock केवल तभी include करें यदि आप CGNAT के पीछे users को break tolerate कर सकते हैं — आमतौर पर नहीं कर सकते।

Chunked Uploads और Multipart Semantics

Resumable chunked uploads के लिए दो credible protocols हैं: tus (IETF draft, Upload-Offset और Upload-Length headers) और S3 multipart (PartNumber, UploadId, ETag)। एक pick करें और commit करें। अपना protocol invent करना tempting लगता है और badly end होता है जब आपको realize होता है कि partial writes, out-of-order chunks, और abandoned sessions handle करने हैं।

REST form में tus pattern:

POST   /sessions              -> 201, Location: /sessions/abc
HEAD   /sessions/abc          -> 200, Upload-Offset: 104857600
PATCH  /sessions/abc          -> 204, body = next chunk
POST   /sessions/abc/complete -> 201, Location: /shares/xyz
DELETE /sessions/abc          -> 204

Chunk size bounds: S3 multipart से match करने के लिए 5 MB minimum, retry cost bounded रखने के लिए 100 MB maximum, default 8 MB। Chunks जो advertised offset से align नहीं होते उन्हें HTTP 409 Conflict plus Problem document expected offset explain करते हुए reject करें।

Rate Limiting जो Real Abuse Reflect करे

Rate limits endpoint cost के अनुसार vary करने चाहिए:

• POST /sessions: 20 per IP per hour (expensive — storage allocate करता है)
• PATCH /sessions/:id: 10,000 per hour per session (cheap — bytes लिखता है)
• GET /shares/:id: 1,000 per IP per hour (metadata lookup)
• GET /shares/:id/download: 100 per IP per hour (egress cost)

Floor protection के लिए edge (Cloudflare, Fastly) पर limits apply करें, और burst control के लिए application पर second layer (express-rate-limit, Fastify का @fastify/rate-limit)। 429 Retry-After seconds में return करें। Successful responses पर भी rate limit headers include करें:

RateLimit-Limit: 20
RateLimit-Remaining: 17
RateLimit-Reset: 2843

IETF RateLimit draft follow करने से well-behaved clients blocked होने के बजाय खुद pace करते हैं।

Error Responses जिन पर Clients Act कर सकें

RFC 7807 Problem Details standard है। हर error Content-Type: application/problem+json return करता है:

{
  "type": "https://api.example.com/errors/chunk-offset-mismatch",
  "title": "Chunk offset mismatch",
  "status": 409,
  "detail": "Server expected offset 5242880, received 4194304.",
  "expected_offset": 5242880,
  "session_id": "abc123"
}

type URI documented और stable होना चाहिए; वही clients pattern-match करते हैं। title generic है; detail specific है। Custom fields machine-actionable context add करते हैं। Errors में stack traces, file paths, या internal IDs कभी leak न करें।

HTTP status codes honestly map करें: malformed input के लिए 400, missing auth के लिए 401, authenticated-but-unauthorized के लिए 403, resource कभी exist नहीं किया के लिए 404 (expired shares के लिए 410 Gone उपयोग करें), over-quota payloads के लिए 413, rate limits के लिए 429, bugs के लिए 500, maintenance के लिए 503।

Content Negotiation और Streaming

Upload endpoints को application/octet-stream accept और Content-Length require करना चाहिए। Chunk uploads के लिए multipart/form-data reject करें — यह parsing overhead add करता है और किसी की help नहीं करता। tus-style partial writes के लिए Content-Range accept करें।

Download endpoints HTTP Range requests (RFC 7233) को resumable downloads के लिए support करने चाहिए:

GET /shares/xyz/blob
Range: bytes=104857600-209715199
-> 206 Partial Content
   Content-Range: bytes 104857600-209715199/2147483648

यही browsers को Wi-Fi hiccup के बाद 2 GB download resume करने देता है। अधिकांश S3-compatible stores Range requests natively serve करते हैं — आपके API को बस forward या presign करना है।

Debt Accumulate किए बिना Versioning

URL path से version करें (/v1/sessions) headers से नहीं। Path versioning logs में visible है, cacheable है, और Accept: application/vnd.example.v1+json से debug करना easier है। v2 ship होने के बाद कम से कम 24 months v1 supported रखें। Fields freely add करें (clients unknown fields ignore करें); stable version में कभी fields remove या rename न करें।

Breaking changes ज़रूरी होने पर, 12 months v1 और v2 parallel चलाएं, v1 responses पर RFC 8594 per Sunset header surface करें, और real before/after examples के साथ migration guides publish करें।

Observability और Debuggability

हर response में correlation ID (X-Request-ID) शामिल होनी चाहिए, request से echoed या generated। ID, client IP (privacy-sensitive हो तो hashed), endpoint, status, और duration structured JSON में log करें। Request bodies log मत करें — इसी तरह encryption keys Datadog में end होती हैं।

Per endpoint metrics emit करें: request count, p50/p95/p99 latency, error rate, bytes in, bytes out। p99 latency spikes और baseline से ऊपर 5xx rate पर alert करें। OpenTelemetry के माध्यम से traces API, storage, और database पर request flow देते हैं।

HexaTransfer का API ऊपर के patterns follow करता है — short resources, tus-style chunk uploads, Problem Details errors, 15-minute presigned downloads, RateLimit headers। hexatransfer.com पर आज़माएं — मुफ़्त, कोई अकाउंट नहीं, अधिकतम 10 GB।

Documentation जो Reality से Match करे

OpenAPI 3.1 spec API के साथ publish करें और server code के same repo में रखें ताकि schema drift PR review issue हो न कि production surprise। Spec से कम से कम एक SDK (TypeScript या Python) generate करें और अपने examples में उपयोग करें — SDK bugs spec bugs fast surface करते हैं। हर endpoint के लिए curl examples include करें, एक quickstart जो 20 lines से कम में real file upload करे, और हर error type URI documenting करने वाला specific page। API जिसे developers एक दोपहर में integrate कर सकें वह एक हफ्ते के reverse engineering वाले से 10x अधिक products पर ship होगा।