Части 1, 2, 3, 4, 5, 6, 7, 8, 9
Сборник правил по проектированию API.
26. Нестрого придерживаемся правил REST-архитектуры.
Если какое-то правило необоснованно осложняет разработку, допускается его обойти.
27. Используем семантическое версионирование приложения.
28. Корень для всех внешних API приложения должен быть указан явно.
Например: /api
29. Корень для всех внутренних API приложения должен быть указан явно. Например: /internal
30. Версию приложения (см.п.27) должно быть видно по адресу:
GET http://host:port/api/actuator/info
31. Health check приложения должен быть доступен по запросу:
GET http://host:port/api/actuator/health
Эндпоинт должен возвращать HTTP код 200, если с приложением всё впорядке.
32. При успешном создании или обновлении сущности по запросу с фронтенда, нужно возвращать в ответе id созданной (изменённой сущности).
Фронту этот id нужен, чтобы переходить на страничку этой сущности. Любую другую информацию передавать нет смысла, так как фронт её проигнорирует и по id отдельным запросом получит от бэкенда всю необходимую информацию.
33. Хорошим тоном является написание валидаторов на входные данные веб-запросов.
Пример хорошей модели для json body запроса:
Пример неудачной модели для json body запроса:
34. Если при валидации веб-запроса были обнаружены ошибки, то возвращать их на фронт нужно в виде пар ключ - значение.
Ключ - это название поля, в котором обнаружена ошибка.
Значение - описание ошибки.
Фронт будет использовать эту информацию для вывода ошибок в веб-форме около полей с невалидными данными.
Пример:
35. При возвращении с бэкенда на фронтенд ошибок, необходимо в ответе указывать requestId (см. пример кода выше).
36. Используйте существительные во множественном числе для обозначения коллекций.
37. Не добавляйте ненужные пути в структуру URL-адресов.
38. Не добавляйте .json или другие расширения к URL-адресу.
39. Не возвращайте массивы в качестве ответов верхнего уровня от эндпоинтов.
Верхний уровень ответа должен быть объектом, а не массивом, чтобы обеспечить обратную совместимость и возможность добавления пагинации.
40. Не возвращайте структуры map.
Вместо этого используйте массивы объектов, чтобы избежать проблем при работе с типизированными языками и не усложнять обработку данных.
41. Не используйте 404 для обозначения события "сущность с таким идентификатором не найдена".
Вместо этого рекомендуется использовать другие коды, чтобы точно указать на отсутствие данных.
Причина: в распределённых системах очень важна согласованность, а код 404 и так уже обозначает слишком многое:
- неправильно сконфигурированный клиент указывает неправильный URL,
- неправильно сконфигурированные прокси (на стороне клиента и на стороне сервера),
- неправильно сконфигурированные балансировщики нагрузки,
- неправильно сконфигурированные таблицы маршрутизации в серверном приложении.
42. Будьте последовательными.
Несоответствие в схемах и структурах может вызвать путаницу и усложнить работу с API.
Необходимо делать всё возможное, чтобы поля одних и тех же объектов и объектов со схожими значениями были согласованными (одинаковые названия, типы данных и т.д.).
43. Обеспечьте механизмы идемпотентности.
Это важно для предотвращения дублирования операций в условиях нестабильной сети.
44. Используйте строки ISO8601 для временных меток.
Строковое представление времени более читаемо и удобно для работы.
45. Используйте фреймворки для автоматического генерирования документации на API.
Например:
- Swagger, Springdoc - для REST,
- graphql-kotlin-spring-server от expediagroup - для GraphQL.