Для тех, кто хочет не просто читать чужую API-документацию, а уметь проектировать REST API методы с нуля — как Backend-разработчики и архитекторы 😎
План 👇
1. Определить клиента API - для кого мы делаем метод, и выбрать конкретный метод к проектированию
2. Заглянуть "под капот" — в Базу Данных
Часто именно тут выясняется, что:
— каких-то данных нет в БД
— или дизайнер не учёл важные поля
— или мы забыли про данные из интеграции
На этом этапе системный аналитик часто ставит доп. задачи на доработку БД или уточняет макеты с дизайнером, так как тот что-то не учёл или наоборот, переборщил.
👉 Здесь важно уметь объяснить команде и заказчикам, что возможно реализовать, а что технически нереализуемо.
3. Определить тип метода и его URL
🔗 Здесь подробно
4. Прописать требования к безопасности
+ вид авторизации,
+ приложения и роли,
+ ограничения по числу запросов,
+ другие ограничения.
5. Сделать требования к заголовкам (headers)
🔗 Здесь подробно
6. Спроектировать тело запроса (если нужно)
Обычно в формате JSON, но может быть XML, HTML, JavaScript, файлы.
7. Спроектировать тело ответа и выбирать успешный статус-код.
Формат сообщения такой же, как в запросе.
Возможные статус-коды:
+ 200 OK,
+ 201 Created (если что-то создано в БД)
и другие.
8. Описать требования к обработке ошибок
Что вернётся, если что-то пошло не так?
Статус-коды + тело JSON + заголовки
9. Продумать алгоритм работы метода
Что делает метод внутри?
Обращается ли к БД?
Интегрируется с внешней системой по API ("под капотом" может быть SOAP, gRPC и любой другой API)?
10. Описать маппинг данных
Таблица, в которой сопоставляем параметры БД, JSON и, если есть интеграция, то также параметры API внешней системы.
11. Дозаполнить шаблон требований
➕ Общее описание
➕ Логирование и мониторинг
➕ Другие доп. требования
Структуру постановки задачи для Confluence с пояснениями можно найти здесь:
🔗 Шаблон требований
#RestApiGA