Dosya transferi API tasarımı: RESTful en iyi uygulamalar

İyi tasarlanmış bir dosya transferi REST API'si beş veya altı kaynak sunar (oturumlar, parçalar, paylaşımlar, indirmeler, iptal işlemleri), HTTP anlamlarını dürüstçe kullanır (oluşturmak için POST, kıpırtısız parçalar için PUT, iptal için DELETE) ve gerçek bayt hareketini ön imzalı depolama URL'lerine iter; böylece sunucunuz bant genişliği darboğazı olmaz. Kimlik doğrulama TLS 1.3 üzerinde kısa ömürlü taşıyıcı belirteçler kullanır, hız sınırları oluşturma ile meta veri okumalarını birbirinden ayırır, parçalı yüklemeler tus sürdürülebilir deseni veya S3 multipart anlamlarını izler ve hatalar RFC 7807 Problem Details formatını kullanarak istemcilerin programatik işlem yapabilmesini sağlar.

Kaynak Modelini Dosyalara Değil Eylemlere Göre Şekillendirin

Yaygın hata, API'yi dosya ağacı olarak modellemektir. Dosya transfer hizmetleri üç kaynak olarak daha iyi modellenir:

/sessions — POST ile oluşturulan, parça PUT'larıyla doldurulan uçuştaki yükleme
/shares — son kullanma tarihi ve indirme bütçesiyle tamamlanmış, adreslenebilir transfer
/downloads — bayt almak için kısa ömürlü, imzalı erişim tanıtıcıları

Oturumlar complete eylemi aracılığıyla paylaşımlara dönüşür; paylaşımlar zaman veya indirme bütçesiyle sona erer. İptal işlemleri paylaşımda PATCH veya iptal belirteciyle DELETE'dir. "Dosya" veya "klasör" için ad yok — bunlar depolamanın uygulama ayrıntıları, genel sözleşmeniz değil.

Bu şekil API yüzeyini küçük tutar (10 uç noktanın altında), HTTP önbelleğe alma ile temiz eşleşir (paylaşımlar Cache-Control: private, max-age=60; indirmeler no-store) ve istemcileri bozmadan depolama arka uçlarını değiştirmenize izin verir.

Kimlik Doğrulama ve Yetkilendirme Desenleri

Kullanıcıya yönelik API'ler için EdDSA ile imzalanmış kısa ömürlü JWT'ler (15 dakikalık TTL) gönderin ve güvenli HttpOnly çerezle yenileyin. Belirteci Authorization: Bearer içine koyun, günlüğe kaydedilen sorgu dizelerine asla koymayın.

Makineden makineye iletişim için HMAC-SHA256 istek imzalama, taşıyıcı belirteçlerden üstündür çünkü anahtarı göndermeden sahipliği kanıtlar. AWS SigV4 referans tasarımdır:

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

Ön imzalı indirme URL'leri için TTL'ler saat değil dakika olmalıdır. 15 dakikalık pencere, sızdırılan URL'nin iletilme riskine karşı kullanılabilirliği dengeler. IP kilidi yalnızca CGNAT arkasındaki kullanıcıları bozmayı göze alabiliyorsanız ekleyin — genellikle alamazsınız.

Parçalı Yüklemeler ve Multipart Anlamları

Sürdürülebilir parçalı yüklemeler için iki güvenilir protokol mevcuttur: tus (IETF taslak, Upload-Offset ve Upload-Length başlıkları) ve S3 multipart (PartNumber, UploadId, ETag). Birini seçin ve kararlı olun. Kendi protokolünüzü icat etmek cazip görünür; kısmi yazmaları, sıra dışı parçaları ve terk edilmiş oturumları ele almanız gerektiğini fark ettiğinizde kötü biter.

REST formunda tus deseni:

POST   /sessions              -> 201, Location: /sessions/abc
HEAD   /sessions/abc          -> 200, Upload-Offset: 104857600
PATCH  /sessions/abc          -> 204, body = sonraki parça
POST   /sessions/abc/complete -> 201, Location: /shares/xyz
DELETE /sessions/abc          -> 204

Parça boyutu sınırları: S3 multipart ile eşleşmek için minimum 5 MB, yeniden deneme maliyetini sınırlı tutmak için maksimum 100 MB, varsayılan 8 MB. Bildirilen ofseti karşılamayan parçaları, beklenen ofseti açıklayan Problem belgesiyle HTTP 409 Conflict döndürerek reddedin.

Gerçek Kötüye Kullanımı Yansıtan Hız Sınırları

Hız sınırlarının uç nokta maliyetine göre değişmesi gerekir:

POST /sessions: IP başına saatte 20 (pahalı — depolama ayırır)
PATCH /sessions/:id: oturum başına saatte 10.000 (ucuz — bayt yazar)
GET /shares/:id: IP başına saatte 1.000 (meta veri sorgusu)
GET /shares/:id/download: IP başına saatte 100 (çıkış maliyeti)

Taban koruma için sınırları kenarda (Cloudflare, Fastly) uygulayın; ani artış kontrolü için uygulama katmanında ikinci bir katman (express-rate-limit, Fastify'ın @fastify/rate-limit) ekleyin. 429 yanıtını saniye cinsinden Retry-After ile döndürün. Başarılı yanıtlara da hız sınırı başlıkları ekleyin:

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

IETF RateLimit taslağını takip etmek, düzgün davranan istemcilerin engellenmeye gerek kalmadan kendi hızını ayarlamasını sağlar.

İstemcilerin Üzerinde İşlem Yapabileceği Hata Yanıtları

RFC 7807 Problem Details standarttır. Her hata Content-Type: application/problem+json döndürür:

{
  "type": "https://api.example.com/errors/chunk-offset-mismatch",
  "title": "Parça ofseti uyuşmazlığı",
  "status": 409,
  "detail": "Sunucu ofset 5242880 bekledi, 4194304 aldı.",
  "expected_offset": 5242880,
  "session_id": "abc123"
}

type URI'si belgelenmiş ve kararlı olmalıdır; istemciler bunu eşleştirme için kullanır. title geneldir; detail özgündür. Özel alanlar makine tarafından işlenebilir bağlam ekler. Hatalarda hiçbir zaman yığın izleri, dosya yolları veya dahili kimlikler sızdırmayın.

HTTP durum kodlarını dürüstçe eşleştirin: 400 hatalı biçimli giriş, 401 eksik kimlik doğrulama, 403 kimliği doğrulanmış-ama-yetkisiz, 404 yalnızca kaynak hiç var olmadığında (süresi dolmuş paylaşımlar için 410 Gone kullanın), 413 kota aşımı yükleri, 429 hız sınırları, 500 hatalar, 503 bakım.

İçerik Müzakeresi ve Akış

Yükleme uç noktaları application/octet-stream kabul etmeli ve Content-Length gerektirmelidir. Parça yüklemeleri için multipart/form-data reddedin — ayrıştırma yükü ekler ve kimseye yardımcı olmaz. tus tarzı kısmi yazmalar için Content-Range kabul edin.

İndirme uç noktaları sürdürülebilir indirmeler için HTTP Aralık isteklerini (RFC 7233) desteklemelidir:

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

Bu, tarayıcıların Wi-Fi kesintisinden sonra 2 GB'lık indirmeye devam etmesini sağlar. Çoğu S3 uyumlu depo Aralık isteklerini natively destekler — API'niz yalnızca yönlendirme veya ön imzalama yapar.

Borç Biriktirmeden Sürümleme

Başlıklar değil URL yolu aracılığıyla sürümlendirin (/v1/sessions). Yol sürümlemesi günlüklerde görünür, önbelleğe alınabilir ve Accept: application/vnd.example.v1+json'dan hata ayıklaması daha kolaydır. v2 yayımlandıktan sonra en az 24 ay boyunca v1'i destekleyin. Alanları özgürce ekleyin (istemciler bilinmeyen alanları görmezden gelmek zorundadır); kararlı bir sürümde alanları asla kaldırmayın veya yeniden adlandırmayın.

Önemli değişiklikler gerektiğinde v1 ve v2'yi 12 ay paralel çalıştırın, v1 yanıtlarına RFC 8594'e göre Sunset başlığı ekleyin ve gerçek öncesi/sonrası örneklerle geçiş kılavuzları yayımlayın.

Gözlemlenebilirlik ve Hata Ayıklanabilirlik

Her yanıt, istekten yansıtılan veya oluşturulan bir korelasyon kimliği içermelidir (X-Request-ID). Kimliği, istemci IP'sini (gizlilik duyarlıysa karma hâlinde), uç noktayı, durumu ve süreyi yapılandırılmış JSON olarak günlüğe kaydedin. İstek gövdelerini günlüğe kaydetmeyin — şifreleme anahtarlarının Datadog'a gitmesi böyle olur.

Uç nokta başına metrik gönderin: istek sayısı, p50/p95/p99 gecikme, hata oranı, gelen bayt, giden bayt. p99 gecikme artışları ve temel çizginin üzerinde 5xx oranı için uyarı verin. OpenTelemetry aracılığıyla izler, API, depolama ve veritabanı genelinde istek akışını verir.

HexaTransfer'in API'si yukarıdaki desenleri izler — kısa kaynaklar, tus tarzı parça yüklemeleri, Problem Details hataları, 15 dakikalık ön imzalı indirmeler, RateLimit başlıkları. hexatransfer.com'da deneyin — ücretsiz, hesap gerekmez, maksimum 10 GB.

Gerçekliği Yansıtan Belgeler

OpenAPI 3.1 spesifikasyonunu API ile birlikte yayımlayın ve sunucu koduyla aynı repoda tutun; böylece şema kayması PR incelemesinde ele alınır, üretim sürprizine dönüşmez. Spesifikasyondan en az bir SDK oluşturun (TypeScript veya Python) ve kendi örneklerinizde kullanın — SDK hataları spesifikasyon hatalarını hızla ortaya çıkarır. Her uç nokta için curl örnekleri, gerçek dosyayı 20 satırın altında yükleyen bir hızlı başlangıç ve her hata type URI'sini belgeleyen özel bir sayfa ekleyin. Geliştiricilerin öğleden sonra entegre edebildiği bir API, bir haftalık tersine mühendislik gerektirenden 10 kat daha fazla ürüne ulaşır.