Tərtibatçılarınızın ilk gündən etibarən izləyə biləcəyi aydın API Sənədləri yazacağam

Niyə əksər API sənədləri uğursuz olur

Onlar son nöqtələri təsvir edir və insanları əslində dayandıran hissələri atlayırlar: necə autentifikasiya etmək, real sorğu necə görünür, səhv nə deməkdir və bununla bağlı nə etmək lazımdır. Oxucu daha sonra dəstək bileti açır ki, bu da sənədləşdirmənin aradan qaldırmaq üçün mövcud olduğu xərcdir.

Mən bunu necə yazıram

Mənbədən, yaddaşdan deyil. Mən marşrutları, doğrulama qatını və səhv idarəedicilərini oxuyuram, sonra real etimadnamələrlə API-ni özüm çağırıram. Sənədlərdəki hər bir nümunə mənim etdiyim bir sorğu və aldığım bir cavabdır — uydurma yüklər yoxdur, son nöqtənin heç vaxt qaytarmadığı status kodları yoxdur.

Sənədlərdə nə var

• Autentifikasiya: token əldə etmək, onu yeniləmək və sessiya zamanı müddəti bitdikdə nə baş verir.
• Parametrləri, tam nümunə sorğusu və real cavab forması ilə hər bir son nöqtə.
• Hər bir səhv kodunu sadəcə mesajı təkrarlamaq əvəzinə səbəbə və düzəlişə uyğunlaşdıran bir səhv istinadı.
• Yeni tərtibatçını sıfırdan on dəqiqədən az müddətdə uğurlu çağırışa aparan bir başlanğıc yolu.
• Tətbiq olunduğu yerlərdə sürət limitləri, səhifələmə, veb-hooklar və idempotensiya izah edilir.

Format

Sizin repozitoriyanızda Markdown, OpenAPI və ya sənədlər saytı üçün strukturlaşdırılmış — hansını ki, əslində saxlayacaqsınız. İstifadəçilərinizin soruşduğu dillərdə kod nümunələri, onları işlətməklə təsdiqlənmişdir. İstəsəniz Postman və ya oxşar kolleksiya daxildir.

Mənə nə lazımdır

Repozitoriya girişi və ya OpenAPI faylı, test mühiti üçün bir işləyən etimadnamə və dəstək komandanızın cavab verməkdən yorulduğu hər hansı suallar. Bu suallar planın əsasını təşkil edir.

Daxil deyil

Marketinq mətni. Bu, proqram təminatının nə etdiyini dəqiq şəkildə sənədləşdirir; açılış səhifəsi fərqli bir sənətdir.

Dönüş və ünsiyyət

İlk tam layihə adətən bir həftə ərzində gəlir və siz onu öz dəstək komandanızın cavab verməyə davam etdiyi suallara qarşı nəzərdən keçirirsiniz. Mən cilalanmış və səhv bir şey təqdim etməkdənsə, kənar halları bilən mühəndis tərəfindən erkən düzəldilməyi üstün tuturam. Son sənəddəki hər bir nümunə sizin API-nizə qarşı icra edilmişdir, buna görə də orada heç bir şey arzuolunan deyil.