Названия и структура
Одинаковые правила для адресов и полей помогают разобраться в новом методе без догадок.
Договориться системам проще
Понятный API начинается с ясных названий, предсказуемых ответов и примеров, которые можно повторить.
Заметки об APIСправочник
Запрос · одно действиеОтвет · понятная структураОшибка · следующий шаг
Основа хорошей интеграции
Разбираем детали, которые экономят время разработчикам по обе стороны соединения.
Ошибки с подсказкой
Ответ об ошибке должен объяснять, что случилось и как исправить запрос.
Примеры рядом
Короткий рабочий пример полезнее длинного списка параметров без контекста.
Быстрая проверка документации
Пройдите путь нового читателя: найдите нужный метод, отправьте первый запрос и попробуйте исправить намеренно неверный.
- Назначение метода описано
- Параметры показаны на примере
- Ответы и ошибки различимы
- Изменения записаны по версиям
Заметки для практики
«Понятный интерфейс» — небольшой справочник о том, как делать технические интеграции предсказуемыми и удобными для людей.