Какие способы проектирования REST API вы знаете?

Основные принципы проектирования REST API

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

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

Ресурсы должны быть существительными во множественном числе, например: /users, /orders. Для вложенных ресурсов используется иерархия: /users/123/orders. Избегайте глаголов в URL, так как действия определяются HTTP методом.

Использование HTTP методов

• GET — получение ресурса или списка ресурсов (без побочных эффектов).
• POST — создание нового ресурса.
• PUT — полная замена ресурса.
• PATCH — частичное обновление ресурса.
• DELETE — удаление ресурса.

Статус коды

Правильные статус коды помогают клиенту понять результат запроса:

• 200 OK — успешный GET, PUT, PATCH.
• 201 Created — успешный POST.
• 204 No Content — успешный DELETE.
• 400 Bad Request — неверный запрос.
• 404 Not Found — ресурс не найден.
• 500 Internal Server Error — ошибка сервера.

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

Чтобы не ломать существующих клиентов, API версионируют. Популярные способы: через URL (/v1/users) или через заголовок Accept: application/vnd.example.v1+json.

Пример кода на Express.js

const express = require('express');
const app = express();
app.use(express.json());

let users = [{ id: 1, name: 'Alice' }];

// GET /users — список пользователей
app.get('/users', (req, res) => {
  res.json(users);
});

// POST /users — создание пользователя
app.post('/users', (req, res) => {
  const user = { id: users.length + 1, ...req.body };
  users.push(user);
  res.status(201).json(user);
});

// GET /users/:id — один пользователь
app.get('/users/:id', (req, res) => {
  const user = users.find(u => u.id === parseInt(req.params.id));
  if (!user) return res.status(404).json({ error: 'User not found' });
  res.json(user);
});

app.listen(3000);

Вывод

Проектирование REST API по этим правилам делает его простым для понимания, масштабируемым и удобным для интеграции. Применяйте такой подход при создании публичных или внутренних API, где важна единообразная структура.