api-design

Amaç

API sözleşmelerini tasarlar veya değiştirir.

Kaynak Skill amacı

Ne zaman kullanılır

Bir görev API yüzeyi eklediğinde veya değiştirdiğinde api-design kullanılır. Projede var olan OpenAPI, GraphQL, protobuf ya da JSON Schema sözleşmesini düzenler; sözleşme yoksa API belgesi yazar. Her işlem için yol, istek ve yanıt biçimleri, hatalar, yetkilendirme, yinelenen istek güvenliği, sayfalama ve sürümleme ele alınır. Kırıcı ve sürümlenmiş değişiklikler tüketici etkisi ve geçiş yolu ile plana taşınır. Mevcut yönlendirmelerden sözleşme belgesi de çıkarabilir.

Mevcut API geleneği adları, harf kullanımını, hata zarfını ve sürümlemeyi belirler. Değişen her işlem bir değişiklik sınıfı alır; kaldırılan veya değiştirilen işlemler uyumluluk için incelenir. Kod varsa tasarım işleyici yolunu, yoksa amaçlanan konumu adlandırır. Çağıranlar, saklama süresi veya sınırlar hakkındaki eksik kararlar uydurulmak yerine soru olarak döndürülür. Bir işlemin kaldırılması her zaman kırıcıdır.

Kaynak Skill amacı

Nasıl çalışır

Becerinin adımları, kaynak sırasıyla

Kaynak Skill akışı

Kapsamı belirle Görevi oku ve kabul ölçütlerinin gerektirdiği işlemleri listele.
Kaynak Skill akışı
Sözleşmeleri bul Taslağa başlamadan mevcut sözleşme biçimini, depo üslubunu ve ilgili işleyicileri bul.
Kaynak Skill akışı
İşlemleri tanımla Her işlemin girdisini, başarılı yanıtını, hatalarını ve yetkisini mevcut biçimde anlat.
Kaynak Skill akışı
Değişiklikleri sınıflandır İşlemleri eklenen, değişen, kaldırılan veya aynı kalan diye ayır ve kırıcı davranışı değerlendir.
Kaynak Skill akışı
Sözleşme etkisini yaz Her kırıcı veya sürümlü değişiklik için tüketicileri ve geçişi belirten plan satırı yaz.
Kaynak Skill akışı
Makine verisini yaz Tasarlanan işlemleri ve sınıflarını API veri dosyasına kaydet.
Kaynak Skill akışı
Tasarımı doğrula API validator'ını çalıştır ve sözleşme verisi geçerli olana dek hataları düzelt.
Kaynak Skill akışı
Kararları bildir Biçimi, işlemleri, kırıcı değişiklikleri, sözleşme satırlarını ve açık soruları özetle.
Kaynak Skill akışı

Temel kurallar

Yeni sözleşme yazmadan önce mevcut olanı bul ve izle.
Kaynak Temel kurallar
Her kırıcı değişikliği uyumluluk kataloğuna göre işaretle.
Kaynak Temel kurallar
Tüketiciler karşılayabiliyorsa eklemeli uyumlu işlemleri tercih et.
Kaynak Temel kurallar
Her işlem için başarılı ve hatalı yanıtları, yetkiyi ve istek davranışını tanımla.
Kaynak Temel kurallar
Deponun adlandırma, hata zarfı, sayfalama ve sürümleme kurallarına uy.
Kaynak Temel kurallar

Çıktı ve gate

Çıktı

Beceri tanımı bir çıktı belirtmiyor.

Kaynak Skill tanımı

gate

Doğrulama başarılı olmalıdır; bildirilmemiş kırıcı veya sürümlü değişiklik tamamlanmayı engeller.
Kaynak Gate kuralı

Kaynak