Ekran kayıtlarıyla API değişiklikleri nasıl belgelenir

API dokümantasyonu temel olarak metin tabanlıdır; uç nokta referansları, parametre tabloları, kimlik doğrulama başlıkları ve kod örnekleri içerir. Bu gayet uygundur. Bir API ile çalışan geliştiricilerin, üzerinde işlem yapacakları bir videoya değil, tarayabilecekleri, okuyabilecekleri ve kopyalayabilecekleri metinlere ihtiyaçları vardır.

Ancak API değişiklik dokümantasyonunun, API referans dokümantasyonundan farklı bir sorunu vardır. Bir API önemli ölçüde değiştiğinde (yeni bir kimlik doğrulama akışı, sayfalama mantığında köklü bir değişiklik, yeni bir webhook yük yapısı gibi), geliştiricilerin sadece neyin değiştiğini değil, neden değiştiğini, geçiş yolunun nasıl göründüğünü ve uygulamalarının doğruluğunu nasıl teyit edeceklerini anlamaları gerekir.

İşte ekran kayıtlarının burada özel ve az kullanılan bir rolü vardır.

Geleneksel API değişiklik dokümantasyonundaki boşluk#

Standart API değişiklik dokümantasyonu "neyi" kapsar: değişikliği açıklayan bir değişiklik günlüğü girişi, yeni parametre yapısını gösteren güncellenmiş referans dokümanları ve kod parçacıkları içeren bir geçiş kılavuzu.

Neyi nadiren iyi kapsar:

Geçiş için geliştirici iş akışı. Yazılı bir geçiş kılavuzu adımları tarif eder. Bir ekran kaydı ise bir geliştiricinin kodunu açtığını, etkilenen çağrıları bulduğunu, değişiklikleri yaptığını, bir sanal alanda test ettiğini ve yanıtı doğruladığını gösterir. Bu iş akışı gösterimi, tek başına kod parçacıklarının sunamayacağı bir bağlam sağlar.

Test ortamı rehberi. Bir API önemli bir değişiklik yayınladığında, geliştiricilerin entegrasyonlarını değişiklik canlıya alınmadan önce test etmeleri gerekir. Bir test ortamının nasıl kurulacağına, hangi isteklerin çalıştırılacağına, beklenen yanıtın nasıl görünmesi gerektiğine ve hataların nasıl yorumlanacağına dair kaydedilmiş bir rehber, uygulama destek taleplerini önemli ölçüde azaltır.

Postman veya curl gösterimi. Yeni bir API özelliğini değerlendiren veya köklü bir değişikliği uygulayan geliştiriciler için, birinin API çağrısı yapmasını izlemek, canlı yanıtı görmek ve her alanın ne anlama geldiğini açıklayan bir anlatımı dinlemek, uç nokta dokümantasyonunu tek başına okumaktan daha hızlıdır.

Ekran kayıtları API dokümantasyonuna ne zaman değer katar#

Tüm API dokümantasyonları videodan fayda sağlamaz. Referans dokümantasyonu (uç nokta tabloları, parametre tanımları, yanıt şemaları) geliştiricilerin ctrl+F ile arayabileceği metin olarak daha iyidir. Bu içerik için video kullanmak herkesin zamanını boşa harcar.

Ekran kayıtlarının gerçek değer kattığı kategoriler:

Kimlik doğrulama ve kimlik bilgisi kurulumu. Çok adımlı kimlik doğrulama akışları (OAuth 2.0 yetkilendirmesi, API anahtarı oluşturma, webhook gizli anahtar yapılandırması) sadece metinle tarif edilmesi zor konulardır. Arayüz ekranlarının sırasını, dikkat edilmesi gereken konsol çıktısını ve kimlik doğrulamanın çalıştığını onaylayan test isteğini göstermek, kurulum destek taleplerini önemli ölçüde azaltır.

Köklü değişiklik geçiş rehberleri. Köklü bir değişiklik, geliştiricilerin entegrasyonlarını güncellemelerini gerektirdiğinde, eski uygulamadan yeniye geçiş yolunu gösteren (çalışan bir kod örneği ve canlı API yanıtı ile) kaydedilmiş bir rehber, çoğu geliştirici için yazılı bir geçiş kılavuzundan daha faydalıdır.

Yeni uç nokta rehberleri. Önemli bir yeni API yeteneği yayınlandığında, uç noktanın kullanımını gösteren 5-8 dakikalık kaydedilmiş bir rehber (ne gönderileceği, ne alınacağı, yaygın hata durumları, pratik kullanım örnekleri), geliştiricilere ilk entegrasyon kodlarını yazmadan önce güven verir.

Webhook olay dokümantasyonu. Webhook yükleri karmaşık olabilir. Bir webhook'un tetiklenmesini, alıcı uç noktadaki ham yükü ve ilgili alanların nasıl ayrıştırılacağını gösteren kaydedilmiş bir rehber, bir JSON şema tablosundan daha fazlasını ifade eder.

SDK kurulumu ve ilk çağrı. İstemci SDK'ları yayınlayan ekipler için, SDK'nın yüklenmesini, ilk kimlik doğrulamalı çağrının yapılmasını ve gerçek bir yanıt alınmasını gösteren bir ekran kaydı, geliştirici yolculuğunun en kritik kısmı olan ilk 15 dakikadaki sürtünmeyi azaltır.

Teknik içerik için sessiz kayıt yaklaşımı#

Geliştirici odaklı ekran kayıtlarının özel bir zorluğu vardır: kaydı yapan kişinin sadece bir GUI'yi değil, gerçek kodları ve API çağrılarını göstermesi gerekir. Bu da terminal, kod düzenleyici, tarayıcı ve muhtemelen Postman gibi bir araç arasında geçiş yapmak anlamına gelir.

Bunu yaparken anlatım yapmak zordur. Senaryolar hazırlık gerektirir. Hataları yeniden kaydetmek sabır ister.

Yapay zeka destekli ekran kaydı araçları bunu çözer. Bir geliştirici veya geliştirici ilişkileri mühendisi, iş akışını gösterirken (terminalde komutlar çalıştırma, API çağrıları yapma, Postman'de yanıtları kontrol etme, kod düzenleme) ekranını sessizce kaydeder. Kayıt sırasında anlatıma gerek yoktur. Yapay zeka iş akışını analiz eder ve her adımda neler olduğunu açıklayan bağlamsal bir anlatım oluşturur.

Çıktı, işini açıklayan yetkin bir geliştirici gibi ses çıkaran anlatımlı bir rehberdir; çünkü anlatım, varsayımsal bir iş akışını tanımlayan bir senaryodan değil, gösterilen gerçek iş akışından üretilir.

API değişiklik dokümantasyonu için video ve metni eşleştirme#

En faydalı API değişiklik dokümantasyonu her iki formatı da birleştirir:

Yazılı bileşen: değişiklik günlüğü girişi (ne değişti ve neden), güncellenmiş referans dokümantasyonu (yeni parametre yapısı, yanıt şeması, hata kodları) ve geçiş kılavuzu (kod parçacıklarıyla adım adım yazılı talimatlar).

Video bileşeni: geçişi pratikte gösteren anlatımlı bir ekran kaydı; gerçek API çağrılarının yapılması, canlı yanıtların görülmesi ve yaygın hata durumlarının ele alınması.

Yazılı bileşen, geliştiricilerin uygulama yaparken geri döndükleri kısımdır. Video ise neyi uygulayacaklarını anlamak için ilk izledikleri şeydir. Videoyu önce izleyen geliştiriciler, geçişleri daha hızlı tamamlar ve daha az destek talebi açarlar çünkü kod yazmaya başlamadan önce iş akışının zihinsel bir modeline sahip olurlar.

API değişiklik dokümantasyonunu güncel tutma#

API dokümantasyonunun kendine has bir eskime sorunu vardır: sürümlüdür. Bir API v2 geçiş kılavuzu, v3 yayınlandıktan sonra geçerli olmayabilecek bir iş akışını tarif eder. Sürüme özel dokümantasyonun net bir şekilde etiketlenmesi, geliştiricilerin güncelliğini yitirmiş geçiş talimatlarını izlemesini engeller.

Canlı gömme (embed) kullanan ekipler için, belirli bir API sürümüne ait video dokümantasyonu net bir şekilde sürümlendirilebilir ve sürüm kullanımdan kaldırıldığında arşivlenebilir. Yeni sürümler, mevcut olanların güncellenmesi yerine yeni kayıtlara sahip olur; böylece eski sürümlerde kalan geliştiriciler için dokümantasyon korunurken, mevcut geçiş yolu netleştirilmiş olur.

Clevera'nın ekran kayıtlarından nasıl anlatımlı teknik rehberler oluşturduğunu görün

Pratik bir API değişiklik dokümantasyonu iş akışı#

Her önemli API değişikliği için:

1. Referans dokümantasyonunu güncelleyin (uç nokta tabloları, parametre tanımları, yanıt şemaları)
2. Değişiklik günlüğü girişini ve geçiş kılavuzunu yazın
3. Geçiş yolunu gösteren sessiz bir ekran kaydı yapın: eski uygulama, değişiklik, yeni uygulama, test ve doğrulama
4. Kaydı yapay zeka anlatımı oluşturma için gönderin
5. Oluşturulan anlatımlı rehberi inceleyin ve yazılı geçiş kılavuzuyla birlikte yayınlayın
6. Videoyu değişiklik günlüğü girişinden, geçiş kılavuzundan ve tüm geliştirici topluluğu duyurularından bağlantılayın

Yapay zeka ekran kaydı araçları kullanılarak video bileşeni için toplam üretim süresi: kayıt ve inceleme dahil 30-45 dakika. Bu ek yük, sprint sürüm iş akışına dahil edilebilecek kadar düşüktür; sürüm sonrası bir sonradan düşünülmüş iş olarak ele alınmasına gerek yoktur.