REST API
REST API — это архитектурный подход, который устанавливает ограничения для API: как они должны быть устроены и какие функции поддерживать.
Зачем
- Производительность
- Масштабируемость
- Гибкость к изменениям
- Отказоустойчивость
- Простота поддержки
- Клиент-серверная архитектура
- Stateless
- Кэширование
- Единообразие интерфейса hateos
- Layered system
- Code on demand
Термины
- Ресурс
- HTTP Method
- URI\URL Ресурса - Универсальный указатель ресурса, который может указывать на любой объект в сети.
- URL — это подмножество URI (Uniform Resource Identifier), которое используется для идентификации ресурсов по их местоположению.
- URI — более общее понятие, которое может включать в себя не только URL, но и другие типы идентификаторов
- пример: https://api.example1.com/users/123 https://api.example2.com/users/123
- Endpoint API - Конкретный URL, определяющий точку взаимодействия с API и функциональность, которую он предоставляет.
- пример: /users/123
- Headers
- Body
- HTTP Status
- HATEOS
Patterns
- Подходы к проектированию
- TODO
- Security
- АвтоДокументация OpenApi
- Версионность
- Сортировка
- Пагинация
- Фильтрация
- HTTP методы
- Эффективное использование кодов ответов HTTP
- Идемпотентность
- Стандартизировать дополнительные машиночитаемые данные в ответе, предпочтительно в форме заголовков HTTP (потому что чтение заголовков не требует вычитывания и разбора всего тела ответа, так что промежуточные прокси и гейтвеи смогут понять семантику ошибки без дополнительных расходов; а так же их можно логировать.
- Файлы
HTTP методы
- POST - Создает, PUT - Создает или заменяет, PATCH - Частичное изменяет, не входит в стандарт HTTP (не рекомендуется использовать)
- GET
- Передача массива в GET:
- ?users=id1,id2
- ?arr[]=1&arr[]=2&arr[]=3&arr[]=4
- ?users=[id1,id2]
- ?users=id1&users=id2
- Передача массива в GET:
- DELETE
- Методы, JSON, URI
- SRP паттерн
RESTful принципы
Пагинация
- Цели Пагинация
- уменьшает объем ненужных данных, передаваемых клиенту
- сокращает объем ненужных вычислений на серверах приложений
- Offset Pagination (limit, offset)
- Seek Pagination
- HATEOS
- Patterns
- Page-Based Pagination
- 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, которые возвращают коллекции, МОГУТ возвращать частичные наборы. Пользователи этих сервисов ДОЛЖНЫ ожидать частичные результирующие наборы и корректно просматривать страницы, чтобы получить весь набор.