Оригинал статьи

Каким бы удобным не было API, пользователь не сможет оценить его без нормальной документации. Документация к API должна включать:

• Пример полного запроса. Это может быть как полный листинг с использованием curl (пример), так и отдельный текст запроса (пример).
• Примеры ожидаемого ответа. При чтении документации к API сильнее всего раздражает непонимание того, что я должен получить при использовании API – приведение в документации макета данных решает эту проблему. Действительно хорошая документация API позволит вам полностью написать враппер, не сделав ни единого запроса.
• Список кодов ошибок и распостраненные причины их появления. Я не фанат Adwords API по многим причинам, но это хороший пример исчерпывающего описания всех возвращаемых кодов ошибок.
• Удобный для поиска Web интерфейс. И не важно, привлекателен ли он внешне, главное, чтобы гугл мог по нему искать. Это не работает, если документация в pdf формате, или для получения доступа к ней нужно авторизоваться.
• Предупреждения об изменении версии и расписание устаревания. Что лучше: версионность или постепенное изменение – спорный вопрос. Но, так или иначе, каждый раз, когда вы вносите изменения, способные сломать чей-то код, необходимо предупреждать об этом. И предупреждение должно быть на вашем сайте с документацией. Иногда изменения связаны с безопасностью и не могут быть подробно описаны, но даже простое предупреждение за пару недель до внесения изменения будет полезно для пользователей. Github API – хороший пример такой документации: видно, что и когда будет удалено, и показана разница между версиями.