Ще напиша ясна API документация, която вашите разработчици могат да следват от първия ден

Защо повечето API документи се провалят

Те описват крайните точки и пропускат частите, които всъщност спират хората: как да се удостоверят, как изглежда реалистична заявка, какво означава грешката и какво да се прави с нея. След това читателят отваря билет за поддръжка, което е цената, която документацията съществува, за да премахне.

Как го пиша

От източника, не по памет. Прочитам маршрутите, слоя за валидиране и обработчиците на грешки, след което сам извиквам API с реални идентификационни данни. Всеки пример в документацията е заявка, която съм направил, и отговор, който съм получил — без измислени данни, без кодове за състояние, които крайната точка никога не връща.

Какво съдържа документацията

• Удостоверяване: получаване на токен, опресняване и какво се случва, когато изтече по време на сесия.
• Всяка крайна точка с параметри, пълен пример за заявка и реалната форма на отговор.
• Справка за грешки, която картографира всеки код за грешка към причина и решение, вместо просто да повтаря съобщението.
• Път за започване, който отвежда нов разработчик от нула до успешно повикване за по-малко от десет минути.
• Обяснени са ограниченията на скоростта, пейджирането, уебкуките и идемпотентността, където те действително се прилагат.

Формат

Markdown във вашето хранилище, структуриран за OpenAPI или сайт за документация — което и да поддържате. Примери за код на езиците, за които вашите потребители питат, проверени чрез изпълнението им. Postman или подобна колекция, включена, ако желаете.

Какво ми е необходимо

Достъп до хранилището или OpenAPI файла, един работещ идентификационен номер за тестова среда и всички въпроси, на които вашият екип за поддръжка е уморен да отговаря. Тези въпроси са очертанието.

Не е включено

Маркетингов текст. Това документира какво прави софтуерът, точно; целевата страница е различно изкуство.

Време за изпълнение и комуникация

Първият пълен проект обикновено пристига в рамките на една седмица и вие го преглеждате спрямо въпросите, на които вашият собствен екип за поддръжка продължава да отговаря. Предпочитам да бъда коригиран рано от инженера, който познава крайните случаи, отколкото да доставя нещо полирано и грешно. Всеки пример в окончателния документ е изпълнен спрямо вашето API, така че нищо в него не е пожелателно.