მე დავწერ მკაფიო API დოკუმენტაციას, რომელსაც თქვენი დეველოპერები პირველივე დღიდან შეძლებენ მიჰყვნენ

რატომ მარცხდება API დოკუმენტების უმეტესობა

ისინი აღწერენ ენდპოინტებს და გამოტოვებენ იმ ნაწილებს, რომლებიც რეალურად აჩერებს ადამიანებს: როგორ მოხდეს ავთენტიფიკაცია, როგორ გამოიყურება რეალისტური მოთხოვნა, რას ნიშნავს შეცდომა და რა უნდა გააკეთოს ამის შესახებ. შემდეგ მკითხველი ხსნის მხარდაჭერის ბილეთს, რაც არის დოკუმენტაციის ღირებულება, რომელიც უნდა მოიხსნას.

როგორ ვწერ მას

წყაროდან და არა მეხსიერებიდან. მე ვკითხულობ მარშრუტებს, ვალიდაციის ფენას და შეცდომების დამმუშავებლებს, შემდეგ კი თავად ვურეკავ API-ს რეალური სერთიფიკატებით. დოკუმენტაციაში არსებული ყველა მაგალითი არის მოთხოვნა, რომელიც მე გავაკეთე და პასუხი, რომელიც მივიღე — არ არის გამოგონილი მონაცემები, არ არის სტატუსის კოდები, რომლებსაც ენდპოინტი არასოდეს აბრუნებს.

რას შეიცავს დოკუმენტაცია

• ავთენტიფიკაცია: ტოკენის მოპოვება, მისი განახლება და რა ხდება, როდესაც ის იწურება სესიის შუა პერიოდში.
• ყველა ენდპოინტი პარამეტრებით, სრული მაგალითის მოთხოვნა და რეალური პასუხის ფორმა.
• შეცდომების მითითება, რომელიც თითოეულ შეცდომის კოდს მიზეზთან და გამოსწორებასთან აკავშირებს, ვიდრე უბრალოდ შეტყობინების გამეორება.
• დაწყების გზა, რომელიც ახალ დეველოპერს ნულიდან წარმატებულ ზარამდე მიჰყავს ათ წუთზე ნაკლებ დროში.
• სიჩქარის ლიმიტები, გვერდების დაყოფა, ვებჰუკები და იდემპოტენტურობა ახსნილია იქ, სადაც ისინი რეალურად გამოიყენება.

ფორმატი

Markdown თქვენს რეპოზიტორიაში, სტრუქტურირებული OpenAPI-სთვის ან დოკუმენტების საიტისთვის — რომელსაც რეალურად შეინარჩუნებთ. კოდის ნიმუშები იმ ენებზე, რომლებსაც თქვენი მომხმარებლები ითხოვენ, შემოწმებული მათი გაშვებით. Postman ან მსგავსი კოლექცია შედის, თუ გსურთ.

რა მჭირდება

რეპოზიტორიაზე წვდომა ან OpenAPI ფაილი, ერთი მოქმედი სერთიფიკატი სატესტო გარემოსთვის და ნებისმიერი შეკითხვა, რომელზეც თქვენი მხარდაჭერის გუნდი დაიღალა პასუხის გაცემით. ეს კითხვები არის მონახაზი.

არ შედის

მარკეტინგული ტექსტი. ეს ზუსტად აღწერს, რას აკეთებს პროგრამული უზრუნველყოფა; სადესანტო გვერდი სხვა ხელობაა.

შესრულების დრო და კომუნიკაცია

პირველი სრული მონახაზი ჩვეულებრივ ერთ კვირაში მოდის და თქვენ მას განიხილავთ იმ კითხვების მიხედვით, რომლებზეც თქვენი მხარდაჭერის გუნდი პასუხობს. მირჩევნია ადრე შემისწოროს ინჟინერმა, რომელმაც იცის ზღვრული შემთხვევები, ვიდრე მივაწოდო რაღაც გაპრიალებული და არასწორი. საბოლოო დოკუმენტში არსებული ყველა მაგალითი შესრულებულია თქვენი API-ის წინააღმდეგ, ამიტომ მასში არაფერია მისწრაფება.