Kurallar — PassportCraft API

Kurallar

Her uç noktada geçerli olan kurallar; yirmi beş kez yinelenmek yerine burada bir kez belirtilmiştir.

İdempotentlik

Bir şeyi değiştiren uç noktalar Idempotency-Key başlığını kabul eder. Aynı anahtarla yinelenen bir istek, etkiyi tekrarlamak yerine özgün yanıtı yeniden oynatır; böylece zaman aşımından sonraki bir deneme ikinci bir pasaport oluşturamaz. Anahtarlar tek bir kuruluşa aittir, dolayısıyla iki müşteri aynı değerde çakışmaz. Test ile canlı ayrıdır: bir kipte kullanılmış anahtar diğerinde yeniden oynatılmaz, reddedilir. Tek istisna, bir olgu değil bir yetkidir: `POST /documents` tarafından döndürülen imzalı yükleme URL’si, dosya henüz gelmediyse yinelemede yeniden üretilir; dosya geldikten sonra ise yanıta eklenmez — süresi dolmuş bir URL, kullanılamayan bir şeyin sadık bir tekrarı olurdu.

Bir anahtar 30 gün boyunca hatırlanır. Bu sürenin ardından tamamen unutulur ve onu taşıyan bir deneme yeniden oynatılmak yerine baştan çalışır; bu nedenle daha geç çalışabilecek bir mutabakat işi yeni bir anahtar üretmelidir.

İstek

curl "https://passportcraft.com/api/v1/organizations/{organization}/passports" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category":"textile"}'

Sayfalama

Koleksiyonlar imleçle sayfalanır, asla konum kaydırmasıyla değil. Eşzamanlı yazma işlemleri varken kaydırma yanlıştır: iki sayfa çağrısı arasında eklenen bir kayıt sonraki tüm kayıtları kaydırır ve istemci farkına varmadan satır atlar ya da yineler.

Sonraki sayfayı almak için next_cursor değerini cursor olarak geri gönderin. Bir imleç, verildiği filtreleri kodlar; farklı filtrelerle gönderilmesi, sessizce başka bir anlama gelen bir sayfa döndürmek yerine reddedilir.

Yanıt

{
  "object": "list",
  "data": [],
  "has_more": true,
  "next_cursor": "eyJjIjoiMjAyNi0wOC0wMVQxNDowMzoyMi41MDFaIn0"
}

Koşullu yazma

Bir pasaportu okumak, sürümünü taşıyan bir ETag döndürür. Bunu bir PATCH isteğinde If-Match olarak geri gönderin; pasaport bu arada değiştiyse yazma reddedilir. Oku-değiştir-yaz döngüsünü eşzamanlı bir düzenleyiciye karşı güvenli kılmanın tek yolu budur.

İstek

curl "https://passportcraft.com/api/v1/organizations/{organization}/passports/{id}" \
  -X PATCH \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "If-Match: \"4\"" \
  -H "Content-Type: application/json" \
  -d '{"data":{"recycled_content_percentage":38}}'

Hız sınırları

Kimliği doğrulanmış her istekte üç sayaç aynı anda işler ve en dar olanı karar verir. Yayımlanan değerler ince ayarlı tavanlar değil, bilinçli olarak temkinli başlangıç noktalarıdır.

Sayaç	İstek	Pencere
key_org	1000	60s
organization	3000	60s
credential	10000	60s
destructive	50	3600s

Sayaca dahil edilen her yanıt, sınırına en çok yaklaşan sayacı adıyla belirten RateLimit ve RateLimit-Policy başlıklarını taşır. Ret yanıtına ayrıca Retry-After eklenir; tahmin yürütmek yerine o süreyi bekleyin.

Kullanılabilir bir anahtar taşımadan gelen bir istek, istemci adresi başına dakikada 60 istek olan ayrı ve çok daha dar bir sayaçla ölçülür. Geçerli bir anahtar için hiçbir zaman geçerli olmaz.

İstek boyutu

Kendi uç noktasının tavanını aşan bir gövde, veritabanına doğru hiçbir şey okunmadan payload_too_large ile reddedilir. Tavan iki kez denetlenir: önce hiçbir maliyeti olmayan, bildirilmiş Content-Length üzerinden, sonra da gerçekten gelen baytlar üzerinden — böylece uzunluk bildirmeyen bir istek de aynı biçimde sınırlı kalır.

Uç noktalar	Tavan
Tek bir kayıt yazan her uç nokta	256 KiB (262144 bytes)
Toplu içe aktarma ve birim yığınları	4 MiB (4194304 bytes)

Yığın tavanı yuvarlak bir sayıdan değil, bu API'nin kabul ettiği en büyük yığından gelir: bir kategorinin her alanı doldurulmuş 500 içe aktarma satırı ya da 1000 serileştirilmiş birim. İkisi de standart tavana sığmaz; o iki uç noktanın kendi tavanının olmasının nedeni tam olarak budur.

Gövde application/json olarak gelmelidir; application/merge-patch+json da kabul edilir. Başka her şey, ayrıştırıcının içinde başarısız olmak yerine unsupported_media_type ile reddedilir — bilinmesi gereken durum curl -d'dir: aksi söylenmedikçe application/x-www-form-urlencoded gönderir. Hiç Content-Type taşımayan bir gövde JSON olarak okunur.

HTTP yöntemleri

Bir uç nokta yalnızca belgelediği yöntemleri yanıtlar. Diğer her yöntem, çalışan yöntemleri sayan bir Allow başlığıyla birlikte method_not_allowed ile reddedilir; yanlış fiile uzanan bir istemci doğrusunu reddin kendisinden öğrenir. HEAD, GET'in çalıştığı her yerde çalışır; OPTIONS her yerde çalışır.

Yanıt

HTTP/1.1 405 Method Not Allowed
Allow: GET, HEAD, PATCH, OPTIONS
Content-Type: application/json

{
  "error": {
    "code": "method_not_allowed",
    "documentation_url": "https://passportcraft.com/docs/api/errors#method_not_allowed",
    "request_id": "req_9Fv2KpQ0aXbT4Lmn",
    "details": { "method": "DELETE", "allowed": ["GET", "HEAD", "PATCH", "OPTIONS"] }
  }
}

Yıkıcı işlemler

Bir pasaportun yayımını geri almak ve bir pasaportu çöp kutusuna taşımak, yayımlanmış bir kaydı piyasadan çeker; bu yüzden ikisi de olağan hız sınırının yanında ayrı bir tavana yazılır. Ucuz ve düzgün biçimlendirilmiş isteklerden oluşan bir döngü, koca bir kataloğu karartabilecek durumda olmamalıdır.

Bir alana belge ekleme

Bazı url alanları bağlantı yerine yüklenmiş bir dosyayı da kabul eder; örneğin bir deney raporu ya da uygunluk beyanı. Önce dosyayı yükleyin, ardından belge kimliğini `data` içinde o alanın eşlik anahtarına yazarak alanı belgeye yönlendirin. Alanın kendisi boş kalabilir: belge kabul eden bir alan, kendisine bir belge eklendiği anda doldurulmuş sayılır; dolayısıyla url’si boş olan bir pasaport yine de doğrulanabilir ve yayımlanabilir.

Bu anahtarı elle oluşturmanız hiçbir zaman gerekmez. Belge kabul eden bir alan, kategori şemasında iki nitelik taşır: kabul edilen türleri listeleyen `document_types` ve yazılacak anahtarı tam olarak belirten `document_id_key`. Adlandırma kuralını varsaymak yerine anahtarı şemadan okuyun; desteklenen tek yol budur. Eşlik anahtarı alanın bir özelliğidir, ayrı bir alan değildir; bu yüzden şemanın `fields` listesinde hiçbir zaman yer almaz.

Şemanın sizin için açıkça yazmadığı bir kural: belgenin `access_tier` değeri alanınkiyle aynı olmalıdır. Genel erişime açık bir belge, “authority” düzeyindeki bir alanı karşılayamaz; ekleme `access_tier_mismatch` ile reddedilir, çünkü düzeyi alanınkinden farklı olan bir belge, alanın göründüğü yerde zaten gösterilmez. Belgeyi, alan tanımının bildirdiği `access_tier` ile oluşturun.

İstek

curl "https://passportcraft.com/api/v1/organizations/{organization}/passports/{id}" \
  -X PATCH \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data":{"conformity_declaration_url__document_id":"doc_123"}}'

Belgeyi ayırmak için eşlik anahtarını boşaltın; dosyanın kendisi siz silene kadar kitaplığınızda kalır. Bir alanın hâlâ işaret ettiği bir belgeyi silerseniz yanıt neyin ayrıldığını bildirir ve bu bildirim yalnızca isteği yapan çağırana ulaşır.

Bir belgenin `upload_state` değeri `ready`, `pending` veya `unknown` olur. `unknown`, baytların depolamada olup olmadığını saptayamadığımız anlamına gelir: ya depolama yanıt vermemiştir ya da satır, bir isteğin yokladığı 25 baytsız belgenin ötesinde kalmıştır. Bunu yok sayılmış değil, belirlenememiş olarak değerlendirin: yayımlamada `unknown`, dosyanın eksik olduğunu bildirmek yerine `storage_unavailable` üretir ve sonraki bir okuma durumu genellikle netleştirir.

İstek tanımlayıcıları

Her yanıt bir Request-Id başlığı taşır; başarıda da hatada da. Destek talebinde bu değeri belirtin, ilgili çağrı tam olarak bulunabilsin.

Olay akışı 30 günlük geçmiş tutar. Bundan daha seyrek sorgulayan bir entegrasyon değişiklikleri kaçırır ve bunun yerine pasaport listesiyle mutabakat sağlamalıdır.