Какие правила следует соблюдать при проектировании REST API?

Проектирование REST API — это создание интерфейса для взаимодействия клиентских приложений с сервером, основанного на архитектурных ограничениях REST (Representational State Transfer). Основная цель — сделать API интуитивно понятным, предсказуемым и легко интегрируемым.

Ключевые принципы и правила

• Ресурсо-ориентированная архитектура: Все данные и сервисы представляются как ресурсы, доступные по уникальным URI. Например, /books — коллекция книг, а /books/123 — конкретная книга.
• Использование HTTP-методов (глаголов): Каждый метод имеет четкую семантику:
  • GET: Получение ресурса или коллекции.
  • POST: Создание нового ресурса.
  • PUT: Полное обновление существующего ресурса.
  • PATCH: Частичное обновление ресурса.
  • DELETE: Удаление ресурса.
  Не используйте глаголы действий в URI (например, /getUser), вместо этого применяйте метод GET к ресурсу /users/{id}.
• Без состояния (Stateless): Сервер не хранит состояние сессии клиента между запросами. Каждый запрос должен содержать всю необходимую информацию (например, токен аутентификации) для его обработки. Это повышает масштабируемость и надежность.
• Использование кодов состояния HTTP: Сообщайте клиенту о результате операции стандартными кодами:
  • 200 (OK) — успешный запрос.
  • 201 (Created) — ресурс создан.
  • 400 (Bad Request) — ошибка в запросе клиента.
  • 404 (Not Found) — ресурс не найден.
  • 500 (Internal Server Error) — ошибка на сервере.
• Стандартный формат данных: Обычно используется JSON для представления ресурсов. Устанавливайте заголовок Content-Type: application/json.
• Версионирование API: Изменения в API не должны ломать существующих клиентов. Версию можно указывать в URI (/api/v1/users) или в заголовках запросов.
• Фильтрация, сортировка, пагинация: Для работы с коллекциями используйте query-параметры, например, GET /users?active=true&sort=name&page=2&limit=20.
• Безопасность: Используйте HTTPS, корректную аутентификацию (например, OAuth 2.0, JWT) и авторизацию на уровне ресурсов.
• HATEOAS (Hypermedia as the Engine of Application State): Расширенный принцип, при котором ответы API содержат гиперссылки на доступные действия (например, ссылку на удаление ресурса), что делает API самоописываемым.

Пример кода (Node.js/Express)

// Пример эндпоинтов для ресурса "books"
const express = require('express');
const app = express();
app.use(express.json());

let books = [{ id: 1, title: 'Clean Code', author: 'Robert Martin' }];

// GET /books — получить все книги
app.get('/api/v1/books', (req, res) => {
  const { author } = req.query; // Пример фильтрации
  let result = books;
  if (author) result = books.filter(b => b.author === author);
  res.status(200).json(result);
});

// POST /books — создать новую книгу
app.post('/api/v1/books', (req, res) => {
  const newBook = { id: books.length + 1, ...req.body };
  books.push(newBook);
  res.status(201).json(newBook); // 201 Created
});

// GET /books/:id — получить книгу по ID
app.get('/api/v1/books/:id', (req, res) => {
  const book = books.find(b => b.id === parseInt(req.params.id));
  if (!book) return res.status(404).json({ error: 'Book not found' });
  res.status(200).json(book);
});

// PUT /books/:id — полностью обновить книгу
app.put('/api/v1/books/:id', (req, res) => {
  const index = books.findIndex(b => b.id === parseInt(req.params.id));
  if (index === -1) return res.status(404).json({ error: 'Book not found' });
  books[index] = { id: books[index].id, ...req.body };
  res.status(200).json(books[index]);
});

// DELETE /books/:id — удалить книгу
app.delete('/api/v1/books/:id', (req, res) => {
  const initialLength = books.length;
  books = books.filter(b => b.id !== parseInt(req.params.id));
  if (books.length === initialLength) {
    return res.status(404).json({ error: 'Book not found' });
  }
  res.status(204).send(); // 204 No Content
});

app.listen(3000, () => console.log('Server running on port 3000'));

Вывод: Соблюдение правил проектирования REST API необходимо для создания интерфейсов, которые легко понимать, использовать, тестировать и поддерживать. Такой подход особенно полезен при разработке публичных API, микросервисов или любых систем, где важна четкая договоренность между клиентом и сервером.