HTTP и REST API: клиент-серверное взаимодействие

Структура HTTP-запроса и ответа, методы GET и POST, коды состояния, принципы REST, проектирование эндпоинтов, аутентификация по токену и документирование API.

Практически любая современная курсовая по разработке содержит клиент и сервер, общающиеся по HTTP. Разберём, как устроен этот обмен и как спроектировать API, за которое не будет стыдно на защите.

Структура запроса и ответа

POST /api/orders HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOi...
Content-Length: 58

{"productId": 42, "quantity": 3, "comment": "срочно"}

--- ответ ---

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/orders/1024

{"id": 1024, "status": "new", "createdAt": "2026-08-17T10:15:00Z"}

Методы

Коды состояния

Разница между 401 и 403 — популярный вопрос: первый означает «мы не знаем, кто вы», второй — «знаем, но вам нельзя». Возврат 200 с текстом ошибки в теле считается плохой практикой: клиент не может отличить успех от сбоя, не разбирая содержимое.

Принципы REST

• Ресурс — существительное во множественном числе: /api/orders, а не /api/getOrders.
• Действие выражается методом, а не адресом: DELETE /api/orders/5 вместо GET /api/deleteOrder?id=5.
• Иерархия через вложенность: /api/orders/5/items.
• Фильтрация, сортировка и постраничность — параметрами строки запроса: ?status=new&sort=-createdAt&page=2&limit=20.
• Отсутствие состояния: каждый запрос самодостаточен, сервер не хранит сессию между вызовами.
• Единообразие: одинаковый формат ошибок и структура ответов по всему API.

Хорошо                              Плохо
GET    /api/products                GET  /api/getAllProducts
GET    /api/products/42             GET  /api/product?id=42
POST   /api/products                POST /api/createProduct
PATCH  /api/products/42             POST /api/updateProduct
DELETE /api/products/42             GET  /api/deleteProduct?id=42
GET    /api/products?category=r&page=2   GET /api/productsByCategoryPage2

Сервер на Express

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

const orders = [];

app.get('/api/orders', (req, res) => {
  const { status, page = 1, limit = 20 } = req.query;
  let result = status ? orders.filter(o => o.status === status) : orders;
  const start = (page - 1) * limit;
  res.json({ total: result.length, items: result.slice(start, start + Number(limit)) });
});

app.get('/api/orders/:id', (req, res) => {
  const order = orders.find(o => o.id === Number(req.params.id));
  if (!order) return res.status(404).json({ error: 'Заказ не найден' });
  res.json(order);
});

app.post('/api/orders', (req, res) => {
  const { productId, quantity } = req.body;
  if (!productId || !Number.isInteger(quantity) || quantity < 1) {
    return res.status(400).json({ error: 'Некорректные данные', fields: ['productId', 'quantity'] });
  }
  const order = { id: orders.length + 1, productId, quantity, status: 'new' };
  orders.push(order);
  res.status(201).location(`/api/orders/${order.id}`).json(order);
});

app.listen(3000);

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

Документирование и тестирование

1. Опишите API в формате OpenAPI (Swagger) — получите наглядную документацию и страницу для ручных проверок.
2. В отчёт включите таблицу эндпоинтов: метод, путь, назначение, коды ответов.
3. Приложите примеры запросов и ответов — по одному на каждый метод.
4. Проверьте API через Postman или curl и вставьте снимки экрана.
5. Опишите обработку ошибок: единый формат тела ответа при сбое.

curl -X POST http://localhost:3000/api/orders \
  -H 'Content-Type: application/json' \
  -d '{"productId": 42, "quantity": 3}' -i

curl 'http://localhost:3000/api/orders?status=new&page=1&limit=10'