Я напишу чітку документацію API, якою ваші розробники зможуть користуватися з першого дня

Чому більшість документації API не працює

Вони описують кінцеві точки та пропускають частини, які насправді зупиняють людей: як автентифікуватися, як виглядає реалістичний запит, що означає помилка та що з нею робити. Потім читач відкриває заявку в службу підтримки, що є вартістю, яку документація має усунути.

Як я це пишу

З джерела, а не з пам'яті. Я читаю маршрути, шар валідації та обробники помилок, потім сам викликаю API з реальними обліковими даними. Кожен приклад у документації — це запит, який я зробив, і відповідь, яку я отримав — без вигаданих корисних навантажень, без кодів стану, які кінцева точка ніколи не повертає.

Що містить документація

• Автентифікація: отримання токена, його оновлення та що відбувається, коли він закінчується в середині сеансу.
• Кожна кінцева точка з параметрами, повний приклад запиту та реальна форма відповіді.
• Довідник помилок, який відображає кожен код помилки на причину та виправлення, а не просто повторює повідомлення.
• Шлях початку роботи, який дозволяє новому розробнику перейти від нуля до успішного виклику менш ніж за десять хвилин.
• Обмеження швидкості, пагінація, вебхуки та ідемпотентність пояснюються там, де вони насправді застосовуються.

Формат

Markdown у вашому репозиторії, структурований для OpenAPI або сайту документації — що б ви не підтримували. Зразки коду мовами, про які запитують ваші користувачі, перевірені шляхом їх виконання. Колекція Postman або подібна включена, якщо ви її хочете.

Що мені потрібно

Доступ до репозиторію або файл OpenAPI, одна робоча облікова інформація для тестового середовища та будь-які питання, на які ваша служба підтримки втомилася відповідати. Ці питання є планом.

Не включено

Маркетинговий текст. Це точно документує, що робить програмне забезпечення; цільова сторінка — це інше ремесло.

Терміни виконання та комунікація

Перший повний чернетка зазвичай надходить протягом тижня, і ви переглядаєте її відповідно до питань, на які ваша власна служба підтримки постійно відповідає. Я б краще, щоб мене виправив на ранній стадії інженер, який знає граничні випадки, ніж надати щось відшліфоване та неправильне. Кожен приклад у фінальному документі був виконаний проти вашого API, тому нічого в ньому не є бажаним.