Kurallar

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.

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

Koşullu yazma

Bir pasaportu okumak, sürümünü hem yanıt gövdesinde hem de ETag olarak döndürür. Sürümü ETag değerini ayrıştırarak değil, yanıt gövdesinden alın: CDN'imiz sıkıştırma yaparken ETag değerini zayıflatabilir, bu yüzden tırnakları kaldırdığınızda geriye W/ öneki kalabilir. Bir PATCH isteğinde bu sürümü Expected-Version ile geri gönderin: pasaport bu arada değiştiyse yazma işlemi reddedilir ve oku-değiştir-yaz döngüsünü eşzamanlı bir düzenleyiciye karşı güvenli kılmanın tek yolu budur. If-Match kullanmayın. Onu okuyan iki uç nokta — bir pasaportu güncellemek ve bir belgeyi ayırmak — joker karakter * dışındaki her değeri reddeder, çünkü CDN'imiz başlığı yanıtla karşılaştırıp sonucu yeniden yazar; yazma işlemi uygulanırdı ve size yine de bir ret olarak bildirilirdi. Diğer uç noktalarda biz onu yok sayarız, ancak CDN'imiz saymayabilir: bir başarıyı, biz yanıt verdikten sonra 412 ile değiştirdiğini gördük. Bu yüzden en güvenlisi başlığı hiç göndermemektir. Başarılı bir PATCH kendi ETag değerini döndürmez; yeni sürüm, yanıt gövdesindeki version alanındadır. Reddedilen bir yazma işlemini YENİ bir Idempotency-Key ile tekrarlayın: ret yanıtı eski anahtara kaydedilmiştir ve yeniden döndürülür.

curl "https://passportcraft.com/api/v1/organizations/{organization}/passports/{id}" \
  -X PATCH \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Expected-Version: 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.

Ölçülen ve kimliği doğrulanmış her yanıt, limitine en çok yaklaşan sayacı belirten RateLimit ve RateLimit-Policy başlıklarını taşır. Reddedilen istekler her yolda Retry-After ekler. Tahmin etmek yerine bu 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.

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.

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.

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.

Yalnızca bazı ürünler için geçerli alanlar

Bir alanın `required` işareti, yayımlama denetiminin o alanı isteyebileceği anlamına gelir. Bu istek ürünün kendisine bağlıysa, alan ayrıca `required_when` taşır ve burada başka bir alanı ve isteği devreye sokan değerleri belirtir. Çevrim ömrü referans testi, `battery_category` için `ev` ve `lmt` değerleriyle `required_when` taşır: Batarya Tüzüğü pasaport verilerini “ilgili batarya kategorisi veya alt kategorisi için geçerli olduğu ölçüde” kapsar ve Komisyon'un batarya pasaportu kılavuzu her veri noktasını geçerli olduğu kategorilere eşler. Bir kategori, birden çok alanı birlikte okuyan bir kural aracılığıyla da bir alanı yeniden isteyebilir — `required_when` bunları tanımlamaz; bunlar doğrulama uç noktasında çözülür.

İkisini birlikte okuyun ve `required` işaretini daha geniş yanıt olarak alın: `required_when` alanını yok sayan bir istemci en fazla gereğinden çoğunu ister. Bir pasaportu hazır sayıp ardından yayımlamanın reddedilmesiyle karşılaşmaz. Belirli bir pasaport için kesin yanıtı, o pasaportu elinde bulunduran doğrulama uç noktası verir.

Belirli bir tarihten itibaren zorunlu olan alanlar

`required_from` içeren bir alan, Brüksel saatine göre belirtilen tarihte yayımlama için zorunlu hâle gelir; bu tarihten önce isteğe bağlıdır. Böyle bir tarihi mümkün olduğunca erken, normalde en az 60 gün önceden duyururuz; bir tüzük daha kısa süre öncesinden bir tarih belirler veya değiştirirse, alan için tüzükteki tarih geçerli olur. `required` değerini `required_when` ve `required_from` ile birlikte okuyun; doğrulama uç noktası, belirli bir pasaport için yanıtı verir.

Pil okumaları

Her okuma bir değeri, kaynağını ve ölçüldüğü veya beyan edildiği tarihi kaydeder. Bir değeri düzeltmek için yeni bir okuma kaydedin. En son gözlem tarihi geçerlidir; tarihler aynıysa daha sonra kaydedilen giriş geçerlidir.

per_battery: override

Bir pil, ilgili alan için kendi okuması olana kadar modelinin değerini kullanır. Model değerinin ölçüm tarihi yoktur.

Tekil bataryalar için başlangıç değerleri (isteğe bağlı)

• Beyan geçerli olduğu sürece, batarya için ilgili değeri kaydedene kadar her sağlık değeri modelden alınır.
• Modelde eksik olan değerler boş kalır. Bu beyanla, sertifikalı enerji durumu %100’den başlar.
• Bir değerin kaydedilmesi, yalnızca o alan için model beyanının yerini alır.
• Kaydettiğiniz ilk durum beyanı korur. Yeniden bir durum kaydederseniz beyan bu batarya için sağlık değerleri sağlamayı bırakır. Aynı durumu seçseniz bile bu geçerlidir.
• Bu batarya için önceden kaydedilmiş değerler korunur.

Eksik zorunlu pil değerleri missing_fields içinde bildirilir. Bunlar pil oluşturmayı veya modelini yayımlamayı engellemez.

İstek tanımlayıcıları

Kimliği doğrulanmış her yanıt, başarıda olduğu gibi hatada da bir Request-Id başlığı taşır. Destek talebinizde bunu belirtirseniz ilgili çağrı tam olarak bulunabilir. İki kategori uç noktası, anahtarsız başarılı istekleri paylaşılan bir önbellekten yanıtlar; bu yanıtlarda Request-Id bulunmaz — reddedilen istekler her yolda mutlaka taşır.

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.