İstekten okunacak bir dokümana

Çoğu API dokümanı üçüncü ayda yalan söylemeye başlar. Kimse yalan söylediği için değil — doküman bir yerde, istekler başka bir yerde yaşadığı ve bir alan değiştiğinde yalnızca biri güncellendiği için.

Lodos bu boşluğu, zaten test ettiğiniz koleksiyondan doküman üreterek kapatıyor. İki modülün yan yana durmasının bütün anlamı bu ve koleksiyonu ilk günden nasıl düzenlemeniz gerektiğini de değiştiriyor.

Koleksiyonu kendinize göre değil, dokümana göre düzenleyin

API Post/Get tüm HTTP metotlarını, klasörlü istek koleksiyonlarını, başlık ve yetkilendirme yönetimini ve sözdizimi renklendirmeli bir yanıt görüntüleyicisini destekliyor. Seçtiğiniz klasör yapısı dokümanınızın yapısı olacak, o yüzden beş dakika düşünmeye değer.

Göreve göre değil kaynağa göre gruplayın. İçinde listeleme, oluşturma, güncelleme ve silme olan users klasörü doküman gibi okunur. Üç farklı kaynaktan üç istek barındıran kayıt akışı klasörü ise sizin karalama defteriniz gibi okunur — çünkü zaten odur.

İstekleri API’nin kendi diliyle adlandırın. GET /users/:id, tek kullanıcı getirden iyidir; çünkü dokümanı okuyan kişi gördüğüyle çağırdığı ucu eşleştirmeye çalışıyordur.

Ömrü belirleyen şey ortam değişkenleri

Bir yıl yaşayan koleksiyonla staging ilk taşındığında çalışmayı bırakan koleksiyon arasındaki fark budur.

Her sunucu adresini, her jetonu ve değişen her tanımlayıcıyı ortam değişkenine koyun. {{base_url}}/users/{{test_user_id}}, tek bir açılır listeyi değiştirerek yerelde, staging’de ve canlıda çalışan bir istektir. URL’sine https://staging-2.example.com gömülmüş bir istek ise üç hafta içinde sessizce bozulur ve sonraki ihtiyaç duyan kişi tarafından yeniden yazılır.

İstek öncesi betikler insanları en çok takan durumu çözüyor: süresi dolan yetkilendirme jetonu. Jetonu istek öncesi adımda alıp ortam değişkenine yazın; her sabah on bir isteğe taze bearer jetonu yapıştırmayı bırakırsınız.

Gizli bilgiler, dürüstçe

Koleksiyon çalışma alanına aittir; yani çalışma alanına erişimi olan herkes onu görebilir — ortamlarınızdaki değerler dahil.

Bunu olduğu gibi bir tasarım kısıtı olarak kabul edin. Geliştirme ve staging kimlik bilgilerinin koleksiyonda olması sorun değil, hatta faydalı; işinizi devralan bir arkadaşınız onları avlamak zorunda kalmamalı. Canlı kimlik bilgileri sorun. Bir değer ekran görüntüsünde sorun olacaksa ortak bir ortamda da işi yoktur.

Pratik kurulum: aşama başına bir ortam ve canlı ortam bilerek eksik bırakılmış olsun — böylece canlıya istek atmak yanlış açılır liste seçimiyle değil, bilinçli bir hareketle mümkün olsun.

Dokümana çevirmek

API Documentation koleksiyondan üretiyor, üstüne zengin metin düzenleyici, sürüm yönetimi, kod parçacığı üretimi, PDF dışa aktarma ve paylaşılabilir bağlantı veriyor.

Üretilen kısım ucun ne olduğunu ve ne aldığını kapsar. Bilemeyeceği şey birinin onu neden çağıracağı — ve okuyucunun asıl ihtiyacı olan kısım da bu. İşleyen desen şöyle:

1. Koleksiyondan üretin. Uç listesini elle yazmayın; kayar.
2. Her kaynak için ne işe yaradığını ve ne zaman kullanılacağını anlatan kısa bir paragraf ekleyin.
3. Hataları belgeleyin. 200’ü değil — e-postanın alınmış olduğu anlamına gelen 409’u ve istemcinin bu durumda ne yapması gerektiğini.
4. Biri özellikle dosya istemedikçe PDF yerine paylaşım bağlantısı yayınlayın. Bağlantı güncel kalır; PDF bir anın fotoğrafıdır.

Dışarıdan tüketicileriniz olduğunda sürüm yönetimi önem kazanır. Birisi üzerine geliştirmeye başladığı noktada bir sürüm kesin; böylece siz bir şeyi değiştirdiğinizde onun neyin üzerine geliştirdiğini anlatan bir belge hâlâ durur.

130 küçük şey

Bir tarayıcı sekmesi kazandırdığı için bilmeye değer: Tools modülünde 130’dan fazla yardımcı araç var — JSON ve XML biçimlendiriciler, kodlayıcılar, dönüştürücüler, hash üreticiler. Tamamen tarayıcınızda çalışıyorlar, hiçbir şey yüklenmiyor ve jeton harcamıyorlar.

Son ayrıntı kulağa geldiğinden önemli. Bir yükü rastgele bir çevrimiçi JSON biçimlendiricisine yapıştırmak, verinizi başkasının sunucusuna yapıştırmak demek. O yükün içinde bir müşterinin bilgileri varsa, bu kimsenin fark etmeyeceği küçük bir olaydır. Yerel araç bu cazibeyi ortadan kaldırıyor.