REST API
REST API — это архитектурный подход, который устанавливает ограничения для API: как они должны быть устроены и какие функции поддерживать.
Зачем
- Производительность
- Масштабируемость
- Гибкость к изменениям
- Отказоустойчивость
- Простота поддержки
- Клиент-серверная архитектура
- Stateless
- Кэширование
- Единообразие интерфейса hateos
- Layered system
- Code on demand
Термины
- Ресурс
- URL
- Headers
- HTTP Status
- HATEOS
Patterns
- Подходы к проектированию
- TODO
- Security
- REST Best Practice - TLS, OAuth, OIDC SSO
- Ролевой доступ (RBAC, ABAC и тп) к методам АПИ
- АвтоДокументация OpenApi
- Версионность
- Сортировка
- Пагинация
- Фильтрация
- Использование SSL
- HTTP методы
- POST, PUT, GET, DELETE
- PATCH - не входит в стандарт HTTP (не рекомендуется использовать)
- Методы, JSON, URI
- SRP паттерн
- Эффективное использование кодов ответов HTTP
- Идемпотентность
- Стандартизировать дополнительные машиночитаемые данные в ответе, предпочтительно в форме заголовков HTTP (потому что чтение заголовков не требует вычитывания и разбора всего тела ответа, так что промежуточные прокси и гейтвеи смогут понять семантику ошибки без дополнительных расходов; а так же их можно логировать.
- Валидация входных данных
- Файлы
- Исключать создание методов массовых изменений
RESTful
Пагинация
- Цели Пагинация
- уменьшает объем ненужных данных, передаваемых клиенту
- сокращает объем ненужных вычислений на серверах приложений
- Offset Pagination (limit, offset)
- Seek Pagination
- HATEOS
- Patterns
- Page-Based Pagination (a somewhat tautological name)
- Offset-Based Pagination
- Cursor-Based Pagination (also known as Token-Based Pagination)
- Time-Based Pagination
- Размер страницы
- Provide a default page size and allow clients to specify their desired page size within reasonable limits
- RESTful API, которые возвращают коллекции, МОГУТ возвращать частичные наборы. Пользователи этих сервисов ДОЛЖНЫ ожидать частичные результирующие наборы и корректно просматривать страницы, чтобы получить весь набор.