Принципы REST

▸Что такое REST

REST (Representational State Transfer) — архитектурный стиль для проектирования веб-сервисов. Основан на HTTP-протоколе.

▸6 ограничений REST

Клиент-сервер архитектура

Stateless

Cacheable

Uniform interface

Layered system

Code on demand (опционально)

Именование ресурсов

▸Правильные URL

code

1GET    /api/users          — список пользователей
2GET    /api/users/123      — конкретный пользователь
3POST   /api/users          — создание пользователя
4PUT    /api/users/123      — обновление пользователя
5DELETE /api/users/123      — удаление пользователя

▸Плохие URL

code

1GET /api/getUsers
2POST /api/createUser
3GET /api/user/delete/123

▸Правила

Используйте существительные, не глаголы

Используйте множественное число

Вложенность для связей: /users/123/posts

Не используйте расширения (.json, .html)

HTTP методы

▸GET

Безопасный и идемпотентный

Не изменяет состояние

Можно кэшировать

▸POST

Создаёт новый ресурс

Не идемпотентный

Возвращает 201 Created

▸PUT

Полная замена ресурса

Идемпотентный

Возвращает 200 OK

▸PATCH

Частичное обновление

Не идемпотентный (обычно)

Возвращает 200 OK

▸DELETE

Удаление ресурса

Идемпотентный

Возвращает 204 No Content

Статус-коды

▸2xx успех

200 OK — успешный запрос

201 Created — ресурс создан

204 No Content — успешно, без тела

▸3xx перенаправление

301 Moved Permanently

304 Not Modified

▸4xx клиентская ошибка

400 Bad Request — неверный запрос

401 Unauthorized — не авторизован

403 Forbidden — доступ запрещён

404 Not Found — не найдено

422 Unprocessable Entity — ошибка валидации

▸5xx серверная ошибка

500 Internal Server Error

502 Bad Gateway

503 Service Unavailable

Формат ответа

▸Успешный ответ

json

1{
2  "status": "success",
3  "data": {
4    "id": 1,
5    "name": "Иван Петров",
6    "email": "ivan@example.com"
7  }
8}

▸Ошибка

json

1{
2  "status": "error",
3  "error": {
4    "code": "VALIDATION_ERROR",
5    "message": "Неверные данные",
6    "details": [
7      {
8        "field": "email",
9        "message": "Некорректный email"
10      }
11    ]
12  }
13}

Пагинация

▸Offset-based

code

1GET /api/users?page=1&limit=20
2GET /api/users?page=2&limit=20

▸Cursor-based

code

1GET /api/users?cursor=abc123&limit=20

▸Формат ответа

json

1{
2  "data": [...],
3  "pagination": {
4    "page": 1,
5    "limit": 20,
6    "total": 100,
7    "totalPages": 5
8  }
9}

Фильтрация и сортировка

▸Фильтрация

code

1GET /api/users?role=admin&status=active

▸Сортировка

code

1GET /api/users?sort=-createdAt,name

▸Поиск

code

1GET /api/users?q=ivan

Версионирование

▸URL версионирование

code

1/api/v1/users
2/api/v2/users

▸Header версионирование

code

1Accept: application/vnd.myapp.v1+json

Безопасность

▸Аутентификация

code

1Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

▸Rate limiting

code

1X-RateLimit-Limit: 100
2X-RateLimit-Remaining: 99

▸CORS

1app.use(cors({
2  origin: 'https://example.com',
3  methods: ['GET', 'POST', 'PUT', 'DELETE'],
4}));

Документация

▸OpenAPI/Swagger

yaml

1paths:
2  /users:
3    get:
4      summary: Список пользователей
5      parameters:
6        - name: page
7          in: query
8          schema:
9            type: integer

Логирование

1app.use((req, res, next) => {
2  const start = Date.now();
3  res.on('finish', () => {
4    const duration = Date.now() - start;
5    console.log(`${req.method} ${req.url} ${res.statusCode} ${duration}ms`);
6  });
7  next();
8});

Заключение

Хороший REST API — это понятный, безопасный и документированный API. Следуйте принципам REST, используйте правильные статус-коды и обеспечивайте безопасность. Документируйте API с помощью OpenAPI.

#nodejs#rest#api#design#best-practices

Node.js≈ 15 мин чтения10 июня 2024 г.

REST API дизайн: best practices и паттерны

Принципы проектирования REST API: именование, статус-коды, пагинация, версионирование и безопасность.

Принципы REST

▸Что такое REST

REST (Representational State Transfer) — архитектурный стиль для проектирования веб-сервисов. Основан на HTTP-протоколе.

▸6 ограничений REST

Клиент-сервер архитектура

Stateless

Cacheable

Uniform interface

Layered system

Code on demand (опционально)

Именование ресурсов

▸Правильные URL

code

1GET    /api/users          — список пользователей
2GET    /api/users/123      — конкретный пользователь
3POST   /api/users          — создание пользователя
4PUT    /api/users/123      — обновление пользователя
5DELETE /api/users/123      — удаление пользователя

▸Плохие URL

code

1GET /api/getUsers
2POST /api/createUser
3GET /api/user/delete/123

▸Правила

Используйте существительные, не глаголы

Используйте множественное число

Вложенность для связей: /users/123/posts

Не используйте расширения (.json, .html)

HTTP методы

▸GET

Безопасный и идемпотентный

Не изменяет состояние

Можно кэшировать

▸POST

Создаёт новый ресурс

Не идемпотентный

Возвращает 201 Created

▸PUT

Полная замена ресурса

Идемпотентный

Возвращает 200 OK

▸PATCH

Частичное обновление

Не идемпотентный (обычно)

Возвращает 200 OK

▸DELETE

Удаление ресурса

Идемпотентный

Возвращает 204 No Content

Статус-коды

▸2xx успех

200 OK — успешный запрос

201 Created — ресурс создан

204 No Content — успешно, без тела

▸3xx перенаправление

301 Moved Permanently

304 Not Modified

▸4xx клиентская ошибка

400 Bad Request — неверный запрос

401 Unauthorized — не авторизован

403 Forbidden — доступ запрещён

404 Not Found — не найдено

422 Unprocessable Entity — ошибка валидации

▸5xx серверная ошибка

500 Internal Server Error

502 Bad Gateway

503 Service Unavailable

Формат ответа

▸Успешный ответ

json

1{
2  "status": "success",
3  "data": {
4    "id": 1,
5    "name": "Иван Петров",
6    "email": "ivan@example.com"
7  }
8}

▸Ошибка

json

1{
2  "status": "error",
3  "error": {
4    "code": "VALIDATION_ERROR",
5    "message": "Неверные данные",
6    "details": [
7      {
8        "field": "email",
9        "message": "Некорректный email"
10      }
11    ]
12  }
13}

Пагинация

▸Offset-based

code

1GET /api/users?page=1&limit=20
2GET /api/users?page=2&limit=20

▸Cursor-based

code

1GET /api/users?cursor=abc123&limit=20

▸Формат ответа

json

1{
2  "data": [...],
3  "pagination": {
4    "page": 1,
5    "limit": 20,
6    "total": 100,
7    "totalPages": 5
8  }
9}

Фильтрация и сортировка

▸Фильтрация

code

1GET /api/users?role=admin&status=active

▸Сортировка

code

1GET /api/users?sort=-createdAt,name

▸Поиск

code

1GET /api/users?q=ivan

Версионирование

▸URL версионирование

code

1/api/v1/users
2/api/v2/users

▸Header версионирование

code

1Accept: application/vnd.myapp.v1+json

Безопасность

▸Аутентификация

code

1Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

▸Rate limiting

code

1X-RateLimit-Limit: 100
2X-RateLimit-Remaining: 99

▸CORS

1app.use(cors({
2  origin: 'https://example.com',
3  methods: ['GET', 'POST', 'PUT', 'DELETE'],
4}));

Документация

▸OpenAPI/Swagger

yaml

1paths:
2  /users:
3    get:
4      summary: Список пользователей
5      parameters:
6        - name: page
7          in: query
8          schema:
9            type: integer

Логирование

1app.use((req, res, next) => {
2  const start = Date.now();
3  res.on('finish', () => {
4    const duration = Date.now() - start;
5    console.log(`${req.method} ${req.url} ${res.statusCode} ${duration}ms`);
6  });
7  next();
8});

Заключение

#nodejs#rest#api#design#best-practices

🛠

Попробуйте наш инструмент

Закрепите знания с помощью интерактивных упражнений

Перейти →

Принципы REST

▸Что такое REST

▸6 ограничений REST

Именование ресурсов

▸Правильные URL

▸Плохие URL

▸Правила

HTTP методы

▸GET

▸POST

▸PUT

▸PATCH

▸DELETE

Статус-коды

▸2xx успех

▸3xx перенаправление

▸4xx клиентская ошибка

▸5xx серверная ошибка

Формат ответа

▸Успешный ответ

▸Ошибка

Пагинация

▸Offset-based

▸Cursor-based

▸Формат ответа

Фильтрация и сортировка

▸Фильтрация

▸Сортировка

▸Поиск

Версионирование

▸URL версионирование

▸Header версионирование

Безопасность

▸Аутентификация

▸Rate limiting

▸CORS

Документация

▸OpenAPI/Swagger

Логирование

Заключение

Попробуйте наш инструмент

Похожие статьи

React: полное руководство для собеседования

JavaScript: глубокий анализ для собеседования

Node.js и backend: что спрашивают на собеседовании

DevOps: от основ до продвинутого уровня

Принципы REST

▸Что такое REST

▸6 ограничений REST

Именование ресурсов

▸Правильные URL

▸Плохие URL

▸Правила

HTTP методы

▸GET

▸POST

▸PUT

▸PATCH

▸DELETE

Статус-коды

▸2xx успех

▸3xx перенаправление

▸4xx клиентская ошибка

▸5xx серверная ошибка

Формат ответа

▸Успешный ответ

▸Ошибка

Пагинация

▸Offset-based

▸Cursor-based

▸Формат ответа

Фильтрация и сортировка

▸Фильтрация

▸Сортировка

▸Поиск

Версионирование

▸URL версионирование

▸Header версионирование

Безопасность

▸Аутентификация