Geliştiricilerinizin İlk Günden İtibaren Takip Edebileceği Açık API Belgeleri Yazacağım

Çoğu API belgesi neden başarısız olur?

Uç noktaları tanımlarlar ve insanları gerçekten durduran kısımları atlarlar: nasıl kimlik doğrulaması yapılır, gerçekçi bir isteğin nasıl göründüğü, hatanın ne anlama geldiği ve bununla ne yapılacağı. Okuyucu daha sonra bir destek bileti açar, bu da belgelerin ortadan kaldırmak için var olduğu maliyettir.

Nasıl yazarım

Kaynaktan, hafızadan değil. Rotaları, doğrulama katmanını ve hata işleyicilerini okur, ardından API'yi gerçek kimlik bilgileriyle kendim çağırırım. Belgelerdeki her örnek, yaptığım bir istek ve aldığım bir yanıttır — uydurma yükler yok, uç noktanın asla döndürmediği durum kodları yok.

Belgeler ne içerir?

• Kimlik Doğrulama: bir token alma, yenileme ve oturum ortasında süresi dolduğunda ne olacağı.
• Parametreleri, eksiksiz bir örnek isteği ve gerçek yanıt şekli ile her uç nokta.
• Her hata kodunu sadece mesajı tekrarlamak yerine bir nedene ve bir düzeltmeye eşleyen bir hata referansı.
• Yeni bir geliştiriciyi sıfırdan on dakikadan kısa sürede başarılı bir çağrıya götüren bir başlangıç yolu.
• Oran limitleri, sayfalama, webhook'lar ve idempotency'nin gerçekten uygulandığı yerlerde açıklanması.

Premium yükseltmesi 5 revizyon ile 3 kaynak ve 500 sayfayı kapsar. Temel katman, hızlı, daha küçük çıkarma görevlerine uygun 2 günde 1 kaynak arasında 100 sayfayı işler.

Deponuzda Markdown, OpenAPI veya bir belge sitesi için yapılandırılmış — hangisini gerçekten sürdürecekseniz. Kullanıcılarınızın sorduğu dillerde kod örnekleri, çalıştırılarak doğrulanmış. İsterseniz Postman veya benzeri bir koleksiyon dahil.

Neye ihtiyacım var

Depo erişimi veya OpenAPI dosyası, bir test ortamı için çalışan bir kimlik bilgisi ve destek ekibinizin yanıtlamaktan yorulduğu tüm sorular. Bu sorular taslağı oluşturur.

Dahil değil

Pazarlama metni. Bu, yazılımın ne yaptığını tam olarak belgeler; açılış sayfası farklı bir zanaattır.

Geri dönüş ve iletişim

İlk eksiksiz taslak genellikle bir hafta içinde gelir ve kendi destek ekibinizin sürekli yanıtladığı sorulara göre incelersiniz. Kenar durumlarını bilen mühendis tarafından erken düzeltilmeyi, cilalı ve yanlış bir şey teslim etmekten daha çok tercih ederim. Son belgedeki her örnek API'nize karşı yürütülmüştür, bu yüzden içinde hiçbir şey arzu edilen değildir.