PrepBro
← Назад к вопросам

Что такое RESTful API?

1.0 Junior🔥 151 комментариев
#Сети и протоколы

Комментарии (1)

🐱
claude-haiku-4.5PrepBro AI29 мар. 2026 г.(ред.)

Ответ сгенерирован нейросетью и может содержать ошибки

Что такое RESTful API?

REST (Representational State Transfer) — это архитектурный стиль для разработки веб-сервисов, основанный на принципах HTTP протокола. RESTful API — это API, разработанный в соответствии с принципами REST архитектуры. Это де-факто стандарт для создания веб-сервисов в современной разработке.

Основные принципы REST

1. Архитектура Client-Server

Клиент и сервер — это отдельные, независимые сущности:

┌─────────────────────┐
│     Клиент          │
│  (Web, Mobile App)  │
└──────────┬──────────┘
           │ HTTP запросы
           ↓
┌─────────────────────┐
│      Сервер         │
│  (RESTful API)      │
└─────────────────────┘

Клиент не должен знать, как реализован сервер, и наоборот.

2. Ресурсы как основа

Всё в REST — это ресурсы, идентифицированные URL'ами:

/api/v1/users          — коллекция пользователей
/api/v1/users/123      — конкретный пользователь с ID 123
/api/v1/users/123/posts — посты пользователя 123
/api/v1/products       — коллекция товаров

3. HTTP методы (глаголы)

Операции над ресурсами выполняются через стандартные HTTP методы:

  • GET — получение ресурса (безопасная, идемпотентная)
  • POST — создание нового ресурса
  • PUT — полное обновление ресурса (идемпотентная)
  • PATCH — частичное обновление ресурса
  • DELETE — удаление ресурса (идемпотентная)
  • HEAD — как GET, но без тела ответа
  • OPTIONS — получение информации о допустимых методах
// Пример на C++ с использованием libcurl
#include <curl/curl.h>
#include <string>

class RESTClient {
private:
    std::string baseURL = "https://api.example.com/api/v1";
    CURL* curl = curl_easy_init();
    
public:
    // GET - получить ресурс
    std::string getUser(int userId) {
        std::string url = baseURL + "/users/" + std::to_string(userId);
        curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
        curl_easy_setopt(curl, CURLOPT_HTTPGET, 1L);
        // Выполнить запрос
        return "user data";
    }
    
    // POST - создать ресурс
    std::string createUser(const std::string& jsonData) {
        std::string url = baseURL + "/users";
        curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
        curl_easy_setopt(curl, CURLOPT_POSTFIELDS, jsonData.c_str());
        curl_easy_setopt(curl, CURLOPT_POST, 1L);
        // Выполнить запрос
        return "created user";
    }
    
    // PUT - обновить ресурс полностью
    std::string updateUser(int userId, const std::string& jsonData) {
        std::string url = baseURL + "/users/" + std::to_string(userId);
        curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
        curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "PUT");
        curl_easy_setopt(curl, CURLOPT_POSTFIELDS, jsonData.c_str());
        // Выполнить запрос
        return "updated user";
    }
    
    // DELETE - удалить ресурс
    void deleteUser(int userId) {
        std::string url = baseURL + "/users/" + std::to_string(userId);
        curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
        curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "DELETE");
        // Выполнить запрос
    }
};

4. Представление ресурсов

Ресурсы могут быть представлены в разных форматах:

  • JSON — современный стандарт
  • XML — классический формат
  • Другие форматы — protobuf, MessagePack и т.д.
// GET /api/v1/users/123
{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com",
  "createdAt": "2024-01-15T10:30:00Z"
}

5. Stateless (без состояния)

Сервер не хранит информацию о клиентах между запросами. Каждый запрос содержит всю необходимую информацию:

Запрос 1: GET /api/v1/users/123
Запрос 2: GET /api/v1/users/456

Сервер не помнит, кто делал запрос 1, при обработке запроса 2.
Каждый запрос независим.

Это позволяет легко масштабировать сервер горизонтально (несколько серверов).

6. Кэшируемость

Ответы должны иметь информацию о кэшировании (Cache-Control, ETag):

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=3600  // Кэшировать на 1 час
ETag: "1234567890"           // Версия ресурса

{"id": 123, "name": "Alice"}

7. Единообразный интерфейс

Согласованный способ взаимодействия клиента и сервера.

Код HTTP статусов

2xx — Успех:

  • 200 OK — успешный GET, PUT, PATCH
  • 201 Created — успешный POST с созданием ресурса
  • 204 No Content — успешный DELETE
  • 206 Partial Content — частичное содержимое

3xx — Перенаправление:

  • 301 Moved Permanently — ресурс переместился
  • 304 Not Modified — кэшированная версия актуальна

4xx — Ошибка клиента:

  • 400 Bad Request — неправильный запрос
  • 401 Unauthorized — требуется аутентификация
  • 403 Forbidden — доступ запрещён
  • 404 Not Found — ресурс не найден
  • 409 Conflict — конфликт (например, дублирование)

5xx — Ошибка сервера:

  • 500 Internal Server Error — внутренняя ошибка
  • 503 Service Unavailable — сервис недоступен

Практический пример: CRUD операции

Система управления блогом:

┌─────────────────────────────────────────────────────┐
│           Стандартные REST операции                 │
├─────────────────────────────────────────────────────┤
│ CREATE   │ POST /api/v1/posts                       │
│          │ Тело: {"title": "...", "content": "..."} │
│          │ Ответ: 201 Created + новый пост         │
├─────────────────────────────────────────────────────┤
│ READ     │ GET /api/v1/posts/5                      │
│          │ Ответ: 200 OK + JSON пост                │
├─────────────────────────────────────────────────────┤
│ UPDATE   │ PUT /api/v1/posts/5                      │
│          │ Тело: {"title": "...", "content": "..."} │
│          │ Ответ: 200 OK + обновлённый пост        │
├─────────────────────────────────────────────────────┤
│ DELETE   │ DELETE /api/v1/posts/5                   │
│          │ Ответ: 204 No Content                    │
└─────────────────────────────────────────────────────┘

Хороший дизайн RESTful API

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

ПЛОХО:
GET  /api/v1/users/getAll
GET  /api/v1/users/123/delete
POST /api/v1/users/create

ХОРОШО:
GET    /api/v1/users           (получить всех)
GET    /api/v1/users/123       (получить одного)
DELETE /api/v1/users/123       (удалить)
POST   /api/v1/users           (создать)

Правило 2: Используй иерархию для связей

/api/v1/users/123/posts              — посты пользователя 123
/api/v1/users/123/posts/456/comments — комментарии поста 456

Правило 3: Versioning

/api/v1/users  — версия 1
/api/v2/users  — версия 2

Это позволяет безопасно вносить изменения в API без break'ов для старых клиентов.

Правило 4: Фильтрация и пагинация

GET /api/v1/posts?page=2&limit=10                        — пагинация
GET /api/v1/posts?status=published&category=tech         — фильтрация
GET /api/v1/posts?sort=-createdAt&fields=id,title,author — сортировка и выбор полей

Аутентификация в RESTful API

1. Token-based (JWT)

1. Клиент: POST /api/v1/auth/login
           {"username": "alice", "password": "secret"}

2. Сервер: 200 OK
           {"token": "eyJhbGciOiJIUzI1NiIs..."}

3. Клиент: GET /api/v1/users/123
           Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

4. Сервер: 200 OK + данные пользователя

2. API Key

GET /api/v1/users/123
X-API-Key: your-secret-api-key-123

3. OAuth 2.0

Больше всего используется для интеграции с внешними сервисами.

Ошибки в дизайне API

Ошибка 1: Игнорирование HTTP статусов

// ПЛОХО
HTTP 200 OK
{
  "status": "error",
  "message": "User not found"
}

// ХОРОШО
HTTP 404 Not Found
{
  "error": "User not found",
  "code": "USER_NOT_FOUND"
}

Ошибка 2: Слишком много вложенности

// ПЛОХО
GET /api/v1/companies/1/departments/2/teams/3/members/4

// ХОРОШО (если часто нужны члены)
GET /api/v1/members/4?company=1&department=2&team=3
или
GET /api/v1/members?team=3

Ошибка 3: Смешивание концепций

ПЛОХО:
GET  /api/v1/users/search?name=alice  (это не стандартно)
POST /api/v1/users/search              (можно, но unusual)

ХОРОШО:
GET /api/v1/users?name=alice           (фильтрация)

Инструменты для тестирования RESTful API

# curl - базовый инструмент
curl -X GET https://api.example.com/api/v1/users
curl -X POST https://api.example.com/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice"}'

# Postman - графический интерфейс
# REST Client VS Code extension
# httpie - более удобный curl
http GET https://api.example.com/api/v1/users

Альтернативы REST

GraphQL: Позволяет клиентам запрашивать только нужные данные.

gRPC: Бинарный протокол для высокопроизводительных систем.

WebSocket: Двусторонняя коммуникация в реальном времени.

Заключение

RESTful API — это мощный и гибкий способ разработки веб-сервисов, основанный на принципах HTTP. Его преимущества:

  1. Простота — легко понять и использовать
  2. Масштабируемость — stateless архитектура
  3. Кэшируемость — встроенная поддержка кэширования
  4. Стандартность — следует стандартам HTTP
  5. Совместимость — работает в любом браузере и клиентском приложении

Для C++ backend разработчика понимание REST является обязательным для создания современных веб-приложений и микросервисов.

Что такое RESTful API? | PrepBro