Проектирование REST API

Проектирование REST API

REST (Representational State Transfer) - это архитектурный стиль для построения распределённых систем поверх HTTP. В этом уроке мы изучим, как создавать понятные, масштабируемые и удобные API.

Принципы REST

1. Client-Server

Клиент и сервер разделены. Клиент не знает о хранении данных, сервер не знает об UI.

2. Stateless

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

# Плохо - сервер помнит контекст
POST /api/search
{ "query": "phones" }

GET /api/next-page  # Сервер должен помнить предыдущий поиск

# Хорошо - каждый запрос самодостаточен
GET /api/products?query=phones&page=1
GET /api/products?query=phones&page=2

3. Cacheable

Ответы должны указывать, можно ли их кешировать.

HTTP/1.1 200 OK
Cache-Control: max-age=3600, public
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"

4. Uniform Interface

Единообразный интерфейс для всех ресурсов.

5. Layered System

Архитектура может состоять из иерархических слоёв.

6. Code on Demand (опционально)

Сервер может отправлять исполняемый код клиенту.

Ресурсы и URL

REST: ресурс как существительное, метод HTTP как действие

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

# Плохо
GET /getUsers
POST /createUser
POST /deleteUser/123

# Хорошо
GET /users
POST /users
DELETE /users/123

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

# Плохо
GET /user
GET /user/123

# Хорошо
GET /users
GET /users/123

Иерархия ресурсов

# Компании
GET /companies
GET /companies/123

# Сотрудники компании
GET /companies/123/employees
GET /companies/123/employees/456

# Можно также обратиться напрямую
GET /employees/456

HTTP методы и их семантика

GET - получение ресурса

GET /users/123 HTTP/1.1

HTTP/1.1 200 OK
{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com"
}

POST - создание ресурса

POST /users HTTP/1.1
Content-Type: application/json

{
  "name": "Jane Doe",
  "email": "jane@example.com"
}

HTTP/1.1 201 Created
Location: /users/124
{
  "id": 124,
  "name": "Jane Doe",
  "email": "jane@example.com"
}

PUT - полное обновление

PUT /users/123 HTTP/1.1
Content-Type: application/json

{
  "name": "John Smith",
  "email": "john.smith@example.com"
}

HTTP/1.1 200 OK
{
  "id": 123,
  "name": "John Smith",
  "email": "john.smith@example.com"
}

PATCH - частичное обновление

PATCH /users/123 HTTP/1.1
Content-Type: application/json

{
  "email": "newemail@example.com"
}

HTTP/1.1 200 OK
{
  "id": 123,
  "name": "John Smith",
  "email": "newemail@example.com"
}

DELETE - удаление

DELETE /users/123 HTTP/1.1

HTTP/1.1 204 No Content

Фильтрация, сортировка и пагинация

Фильтрация

# Простая фильтрация
GET /products?category=electronics&price_min=100&price_max=500

# Сложная фильтрация
GET /products?filter[category]=electronics&filter[price][gte]=100&filter[price][lte]=500

Сортировка

# Простая сортировка
GET /products?sort=price
GET /products?sort=-price  # По убыванию

# Множественная сортировка
GET /products?sort=-price,name

Пагинация

Offset-based:

GET /products?offset=20&limit=10

{
  "data": [...],
  "meta": {
    "total": 100,
    "offset": 20,
    "limit": 10
  }
}

Page-based:

GET /products?page=3&per_page=10

{
  "data": [...],
  "meta": {
    "total": 100,
    "page": 3,
    "per_page": 10,
    "total_pages": 10
  }
}

Cursor-based:

GET /products?cursor=eyJpZCI6MTIzfQ==&limit=10

{
  "data": [...],
  "meta": {
    "next_cursor": "eyJpZCI6MTMzfQ==",
    "has_more": true
  }
}

Для больших наборов данных cursor-based эффективнее всех: курсор хранит, где остановились (например, {"id":123} в Base64), и БД сразу прыгает к нужному месту по индексу (WHERE id > 123 LIMIT 10). При offset и page БД всё равно читает и отбрасывает первые N строк, поэтому offset=100000 медленный, а при вставке новых строк между запросами страницы «съезжают» - элементы дублируются или теряются. Offset/page проще и позволяют прыгнуть на страницу N - этого хватает для небольших списков.

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

1. В URL

GET https://api.example.com/v1/users
GET https://api.example.com/v2/users

2. В заголовке

GET https://api.example.com/users
Accept: application/vnd.myapi.v2+json

3. В query параметре

GET https://api.example.com/users?version=2

Версия в URL проще всего: её видно в логах, документации и в браузере, её легко отлаживать через curl. Версия в заголовке Accept считается более «каноничной» для REST (URL обозначает ресурс, а не версию), но её не видно в адресе, и отлаживать сложнее. На практике чаще выбирают URL.

Стратегия версионирования

import "net/http"

// newRouter поддерживает несколько версий: у каждой свой набор маршрутов.
// v1Routes и v2Routes возвращают http.Handler с эндпоинтами своей версии.
func newRouter() http.Handler {
    mux := http.NewServeMux()
    mux.Handle("/api/v1/", http.StripPrefix("/api/v1", deprecated(v1Routes())))
    mux.Handle("/api/v2/", http.StripPrefix("/api/v2", v2Routes()))
    return mux
}

// deprecated добавляет Deprecation-заголовки ко всем ответам старой версии.
func deprecated(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Deprecation", "@1767225599")                 // устарела с 31.12.2025 (unix-время)
        w.Header().Set("Sunset", "Fri, 31 Dec 2027 23:59:59 GMT") // отключим после этой даты
        w.Header().Set("Link", `</api/v2>; rel="successor-version"`)
        next.ServeHTTP(w, r)
    })
}
<?php
declare(strict_types=1);

// Поддержка нескольких версий: префикс URL выбирает набор маршрутов
// (в Symfony/Laravel это группы маршрутов с prefix и middleware)
$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);

if (str_starts_with($path, '/api/v1/')) {
    $prefix = '/api/v1';
    // Deprecation-заголовки для всех ответов v1
    header('Deprecation: @1767225599');               // устарела с 31.12.2025 (unix-время)
    header('Sunset: Fri, 31 Dec 2027 23:59:59 GMT'); // отключим после этой даты
    header('Link: </api/v2>; rel="successor-version"');
    $router = new V1Router();
} elseif (str_starts_with($path, '/api/v2/')) {
    $prefix = '/api/v2';
    $router = new V2Router();
} else {
    http_response_code(404);
    exit;
}

// Роутер версии получает путь без своего префикса
$router->dispatch(substr($path, strlen($prefix)));
from collections.abc import Callable, Iterable
from typing import Any

StartResponse = Callable[..., Any]
WSGIApp = Callable[[dict[str, Any], StartResponse], Iterable[bytes]]

DEPRECATION_HEADERS = [
    ("Deprecation", "@1767225599"),  # устарела с 31.12.2025 (unix-время)
    ("Sunset", "Fri, 31 Dec 2027 23:59:59 GMT"),  # отключим после этой даты
    ("Link", '</api/v2>; rel="successor-version"'),
]


def deprecated(app: WSGIApp) -> WSGIApp:
    """Добавляет Deprecation-заголовки ко всем ответам старой версии."""
    def wrapper(environ: dict[str, Any], start_response: StartResponse) -> Iterable[bytes]:
        def start(status: str, headers: list[tuple[str, str]], exc_info: Any = None) -> Any:
            return start_response(status, headers + DEPRECATION_HEADERS, exc_info)
        return app(environ, start)
    return wrapper


def versioned(routes: dict[str, WSGIApp]) -> WSGIApp:
    """Выбирает набор маршрутов по префиксу /api/vN."""
    def app(environ: dict[str, Any], start_response: StartResponse) -> Iterable[bytes]:
        path = environ["PATH_INFO"]
        for prefix, version_app in routes.items():
            if path.startswith(prefix + "/"):
                environ["PATH_INFO"] = path[len(prefix):]
                return version_app(environ, start_response)
        start_response("404 Not Found", [])
        return [b""]
    return app


# Поддержка нескольких версий
# (в FastAPI это app.include_router(v1_router, prefix="/api/v1"))
application = versioned({
    "/api/v1": deprecated(v1_app),
    "/api/v2": v2_app,
})

Заголовки сообщают клиенту два разных момента. Deprecation (RFC 9745) - с какого момента версия считается устаревшей: структурированная дата, @ и unix-время (@1767225599 - 31 декабря 2025, 23:59:59 UTC). В ранних черновиках стандарта писали Deprecation: true, сейчас так не делают. Sunset (RFC 8594) - обычная HTTP-дата, после которой версия перестанет отвечать. Link с rel="successor-version" подсказывает, куда переезжать.

Обработка ошибок

Используйте правильные HTTP коды

# 400 Bad Request - неверный формат запроса
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request format",
    "details": {
      "email": "Invalid email format"
    }
  }
}

# 401 Unauthorized - нет аутентификации
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

# 403 Forbidden - нет прав
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You don't have permission to access this resource"
  }
}

# 404 Not Found - ресурс не найден
HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "code": "NOT_FOUND",
    "message": "User not found"
  }
}

# 422 Unprocessable Entity - ошибка валидации
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "errors": [
      {
        "field": "email",
        "code": "invalid_format",
        "message": "Email must be a valid email address"
      }
    ]
  }
}

Консистентный формат ошибок

import (
    "encoding/json"
    "errors"
    "log/slog"
    "net/http"
    "strings"
)

// APIError - единый формат ошибки для всех эндпоинтов.
type APIError struct {
    Status  int               `json:"-"`
    Code    string            `json:"code"`
    Message string            `json:"message"`
    Details map[string]string `json:"details,omitempty"`
}

func (e *APIError) Error() string { return e.Code + ": " + e.Message }

// writeError отдаёт ошибку в виде {"error": {...}} с нужным статусом.
func writeError(w http.ResponseWriter, err error) {
    var apiErr *APIError
    if !errors.As(err, &apiErr) {
        // Детали внутренней ошибки - только в лог, не клиенту
        slog.Error("unhandled error", slog.String("err", err.Error()))
        apiErr = &APIError{Status: http.StatusInternalServerError, Code: "INTERNAL", Message: "Internal server error"}
    }
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(apiErr.Status)
    _ = json.NewEncoder(w).Encode(map[string]*APIError{"error": apiErr})
}

// Использование: слой ниже возвращает *APIError как обычную ошибку,
// обработчик отдаёт её через writeError.
func validateEmail(email string) error {
    if !strings.Contains(email, "@") {
        return &APIError{
            Status:  http.StatusUnprocessableEntity,
            Code:    "VALIDATION_ERROR",
            Message: "Validation failed",
            Details: map[string]string{"email": "Invalid format"},
        }
    }
    return nil
}
<?php
declare(strict_types=1);

// Единый формат ошибки для всех эндпоинтов
final class ApiError extends RuntimeException
{
    /** @param array<string, string> $details */
    public function __construct(
        public readonly string $errorCode,
        string $message,
        public readonly int $status,
        public readonly array $details = [],
    ) {
        parent::__construct($message);
    }

    /** @return array{error: array<string, mixed>} */
    public function toArray(): array
    {
        $error = ['code' => $this->errorCode, 'message' => $this->getMessage()];
        if ($this->details !== []) {
            $error['details'] = $this->details;
        }
        return ['error' => $error];
    }
}

// Где-то в обработчике запроса:
// throw new ApiError('VALIDATION_ERROR', 'Validation failed', 422, ['email' => 'Invalid format']);

// Обработчик на верхнем уровне ловит ApiError из любого эндпоинта
// (в Symfony это kernel.exception listener, в Laravel - render() в exception handler)
try {
    $router->dispatch($request);
} catch (ApiError $e) {
    http_response_code($e->status);
    header('Content-Type: application/json');
    echo json_encode($e->toArray(), JSON_THROW_ON_ERROR);
}
import json
from dataclasses import dataclass, field


@dataclass
class APIError(Exception):
    """Единый формат ошибки для всех эндпоинтов."""

    code: str
    message: str
    status: int
    details: dict[str, str] = field(default_factory=dict)

    def __str__(self) -> str:
        """Без этого str(e) вернёт кортеж аргументов, а не текст ошибки."""
        return self.message

    def to_body(self) -> dict[str, dict[str, object]]:
        """Тело ответа в виде {"error": {...}}."""
        error: dict[str, object] = {"code": self.code, "message": self.message}
        if self.details:
            error["details"] = self.details
        return {"error": error}


def error_response(e: APIError) -> tuple[int, bytes]:
    """Обработчик на верхнем уровне (в FastAPI это @app.exception_handler(APIError))."""
    return e.status, json.dumps(e.to_body()).encode()


# Использование
raise APIError("VALIDATION_ERROR", "Validation failed", 422, {"email": "Invalid format"})

HATEOAS

HATEOAS (Hypermedia as the Engine of Application State) - клиент взаимодействует с приложением через гиперссылки.

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "_links": {
    "self": {
      "href": "/users/123"
    },
    "posts": {
      "href": "/users/123/posts"
    },
    "following": {
      "href": "/users/123/following"
    },
    "followers": {
      "href": "/users/123/followers"
    }
  }
}

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

OpenAPI (Swagger)

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
  description: API для управления пользователями

paths:
  /users:
    get:
      summary: Получить список пользователей
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: Успешный ответ
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  meta:
                    $ref: '#/components/schemas/Pagination'

    post:
      summary: Создать пользователя
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
      responses:
        '201':
          description: Пользователь создан
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email

    CreateUser:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
        email:
          type: string
          format: email

    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer

Инструменты для документации

  1. Swagger UI - интерактивная документация
  2. Postman - коллекции и документация
  3. Redoc - красивая документация из OpenAPI
  4. API Blueprint - markdown-based документация

Best Practices

1. Используйте правильные Content-Type

# JSON
Content-Type: application/json

# XML
Content-Type: application/xml

# Form data
Content-Type: application/x-www-form-urlencoded

# Multipart (файлы)
Content-Type: multipart/form-data

2. Поддерживайте content negotiation

# Клиент запрашивает JSON
GET /users/123
Accept: application/json

# Клиент запрашивает XML
GET /users/123
Accept: application/xml

3. Используйте правильные статус коды

import (
    "encoding/json"
    "net/http"
)

// writeJSON выставляет Content-Type, статус и пишет тело.
func writeJSON(w http.ResponseWriter, status int, v any) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)
    _ = json.NewEncoder(w).Encode(v)
}

// respond показывает статус для каждого исхода; в обработчике срабатывает одна ветка.
func respond(w http.ResponseWriter, outcome string, user any) {
    switch outcome {
    case "created": // Создание ресурса
        writeJSON(w, http.StatusCreated, user)
    case "deleted": // Успешное удаление - тела нет
        w.WriteHeader(http.StatusNoContent)
    case "not_found": // Ресурс не найден
        writeJSON(w, http.StatusNotFound, map[string]string{"error": "Not found"})
    default: // Ошибка сервера
        writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "Internal server error"})
    }
}
<?php
declare(strict_types=1);

// Статус, Content-Type и JSON-тело
// (в Symfony это new JsonResponse($data, 201), в Laravel - response()->json($data, 201))
function respond(int $status, ?array $body = null): void
{
    http_response_code($status);
    if ($body !== null) {
        header('Content-Type: application/json');
        echo json_encode($body, JSON_THROW_ON_ERROR);
    }
}

respond(201, $user);                                // Создание ресурса
respond(204);                                       // Успешное удаление - тела нет
respond(404, ['error' => 'Not found']);             // Ресурс не найден
respond(500, ['error' => 'Internal server error']); // Ошибка сервера
import json
from http import HTTPStatus

Response = tuple[HTTPStatus, dict[str, str], bytes]


def respond(status: HTTPStatus, body: object | None = None) -> Response:
    """Статус, заголовки и JSON-тело (в FastAPI это JSONResponse(body, status_code=...))."""
    if body is None:
        return status, {}, b""
    return status, {"Content-Type": "application/json"}, json.dumps(body).encode()


respond(HTTPStatus.CREATED, user)                                             # Создание ресурса
respond(HTTPStatus.NO_CONTENT)                                                # Успешное удаление - тела нет
respond(HTTPStatus.NOT_FOUND, {"error": "Not found"})                         # Ресурс не найден
respond(HTTPStatus.INTERNAL_SERVER_ERROR, {"error": "Internal server error"})  # Ошибка сервера

4. Идемпотентность

  • GET, PUT, DELETE должны быть идемпотентными
  • POST не идемпотентен
  • PATCH в общем случае не идемпотентен: PATCH вида «добавь элемент в список» или «прибавь 1» при повторе меняет ресурс ещё раз. PATCH, который просто задаёт значения полей, на практике идемпотентен, но стандарт этого не требует
# PUT идемпотентен - многократные вызовы дают тот же результат
PUT /users/123
{ "name": "John", "email": "john@example.com" }

# POST не идемпотентен - каждый вызов создаёт новый ресурс
POST /users
{ "name": "John", "email": "john@example.com" }

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

import (
    "net"
    "net/http"
    "net/mail"
    "os"
    "slices"
    "strings"
    "sync"
    "time"
    "unicode/utf8"
)

// Rate limiting: до 100 запросов за 15 минут с одного IP, фиксированное окно.
// Плавнее - token bucket, golang.org/x/time/rate.
// Счётчики в памяти процесса - только для примера: в проде - Redis с TTL,
// иначе память растёт и лимит не общий для нескольких инстансов.
type RateLimiter struct {
    mu     sync.Mutex
    limit  int
    window time.Duration
    hits   map[string]*counter
}

type counter struct {
    count   int
    resetAt time.Time
}

func NewRateLimiter(limit int, window time.Duration) *RateLimiter {
    return &RateLimiter{limit: limit, window: window, hits: make(map[string]*counter)}
}

func (rl *RateLimiter) allow(ip string) bool {
    rl.mu.Lock()
    defer rl.mu.Unlock()

    now := time.Now()
    c, ok := rl.hits[ip]
    if !ok || now.After(c.resetAt) {
        // Окно истекло или IP новый - начинаем счёт заново
        rl.hits[ip] = &counter{count: 1, resetAt: now.Add(rl.window)}
        return true
    }
    c.count++
    return c.count <= rl.limit
}

func (rl *RateLimiter) Middleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        ip, _, err := net.SplitHostPort(r.RemoteAddr)
        if err != nil {
            // Без порта: берём адрес целиком, иначе все такие клиенты делят один счётчик
            ip = r.RemoteAddr
        }
        if !rl.allow(ip) {
            w.Header().Set("Retry-After", "900")
            http.Error(w, "Too Many Requests", http.StatusTooManyRequests)
            return
        }
        next.ServeHTTP(w, r)
    })
}

// CORS: только origin из ALLOWED_ORIGINS, с cookies.
func cors(next http.Handler) http.Handler {
    allowed := strings.Split(os.Getenv("ALLOWED_ORIGINS"), ",")
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Ответ зависит от Origin - кэши должны это учитывать для любого запроса
        w.Header().Add("Vary", "Origin")
        if origin := r.Header.Get("Origin"); origin != "" && slices.Contains(allowed, origin) {
            w.Header().Set("Access-Control-Allow-Origin", origin)
            w.Header().Set("Access-Control-Allow-Credentials", "true")
        }
        if r.Method == http.MethodOptions {
            // Preflight: какие методы и заголовки разрешены в основном запросе
            w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, PATCH, DELETE")
            w.Header().Set("Access-Control-Allow-Headers", "Authorization, Content-Type")
            w.WriteHeader(http.StatusNoContent)
            return
        }
        next.ServeHTTP(w, r)
    })
}

// Security headers
func securityHeaders(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        h := w.Header()
        h.Set("X-Content-Type-Options", "nosniff")
        h.Set("X-Frame-Options", "DENY")
        h.Set("Strict-Transport-Security", "max-age=31536000; includeSubDomains")
        h.Set("Content-Security-Policy", "default-src 'none'")
        next.ServeHTTP(w, r)
    })
}

// Input validation
type CreateUser struct {
    Email string `json:"email"`
    Name  string `json:"name"`
}

func (c CreateUser) Validate() map[string]string {
    errs := map[string]string{}
    // ParseAddress принимает и "Name <a@b.c>" - требуем голый адрес
    if addr, err := mail.ParseAddress(c.Email); err != nil || addr.Address != c.Email {
        errs["email"] = "Invalid email format"
    }
    if utf8.RuneCountInString(c.Name) < 2 {
        errs["name"] = "Must be at least 2 characters"
    }
    return errs
}

// withMiddleware собирает цепочку middleware вокруг всего роутера.
func withMiddleware(mux http.Handler) http.Handler {
    limiter := NewRateLimiter(100, 15*time.Minute)
    return limiter.Middleware(cors(securityHeaders(mux)))
}
<?php
declare(strict_types=1);

// Rate limiting: до 100 запросов за 15 минут с одного IP, фиксированное окно.
// PHP не держит память между запросами, поэтому счётчики сразу в Redis с TTL:
// память не растёт (ключи истекают), лимит общий для нескольких инстансов.
// (в Symfony это компонент RateLimiter, в Laravel - middleware throttle)
function rateLimit(Redis $redis, string $ip): void
{
    $window = 900;
    $key = 'rl:' . $ip . ':' . intdiv(time(), $window);
    // INCR + EXPIRE отдельно не атомарны: упадём между ними - ключ останется без TTL.
    // SET NX EX создаёт ключ сразу с TTL (если его нет), INCR дальше TTL не сбрасывает.
    $redis->set($key, 0, ['nx', 'ex' => $window]);
    $count = $redis->incr($key);
    if ($count > 100) {
        http_response_code(429);
        header('Retry-After: 900');
        exit;
    }
}

// CORS: только origin из ALLOWED_ORIGINS, с cookies
function cors(): void
{
    $allowed = explode(',', getenv('ALLOWED_ORIGINS') ?: '');
    $origin = $_SERVER['HTTP_ORIGIN'] ?? '';
    // Ответ зависит от Origin - кэши должны это учитывать для любого запроса
    header('Vary: Origin');
    if ($origin !== '' && in_array($origin, $allowed, true)) {
        header('Access-Control-Allow-Origin: ' . $origin);
        header('Access-Control-Allow-Credentials: true');
    }
    if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
        // Preflight: какие методы и заголовки разрешены в основном запросе
        header('Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE');
        header('Access-Control-Allow-Headers: Authorization, Content-Type');
        http_response_code(204);
        exit;
    }
}

// Security headers
function securityHeaders(): void
{
    header('X-Content-Type-Options: nosniff');
    header('X-Frame-Options: DENY');
    header('Strict-Transport-Security: max-age=31536000; includeSubDomains');
    header("Content-Security-Policy: default-src 'none'");
}

// Input validation
/**
 * @param array<string, mixed> $input
 * @return array<string, string>
 */
function validateCreateUser(array $input): array
{
    $errors = [];
    if (filter_var($input['email'] ?? '', FILTER_VALIDATE_EMAIL) === false) {
        $errors['email'] = 'Invalid email format';
    }
    if (mb_strlen((string) ($input['name'] ?? '')) < 2) {
        $errors['name'] = 'Must be at least 2 characters';
    }
    return $errors;
}
import os
import re
import time
from dataclasses import dataclass, field

# Rate limiting: до 100 запросов за 15 минут с одного IP, фиксированное окно.
# Счётчики в памяти процесса - только для примера: в проде - Redis с TTL,
# иначе память растёт и лимит не общий для нескольких инстансов
# (в FastAPI это обычно middleware или библиотека slowapi).


@dataclass
class RateLimiter:
    """Считает запросы IP в текущем окне."""

    window: int = 15 * 60
    limit: int = 100
    _hits: dict[tuple[str, int], int] = field(default_factory=dict)

    def allow(self, ip: str, now: float | None = None) -> bool:
        bucket = int((time.time() if now is None else now) // self.window)
        key = (ip, bucket)
        self._hits[key] = self._hits.get(key, 0) + 1
        return self._hits[key] <= self.limit


ALLOWED_ORIGINS = {o for o in os.environ.get("ALLOWED_ORIGINS", "").split(",") if o}


def cors_headers(origin: str | None, method: str) -> dict[str, str]:
    """CORS: только origin из ALLOWED_ORIGINS, с cookies."""
    # Ответ зависит от Origin - кэши должны это учитывать для любого запроса
    headers = {"Vary": "Origin"}
    if origin is not None and origin in ALLOWED_ORIGINS:
        headers["Access-Control-Allow-Origin"] = origin
        headers["Access-Control-Allow-Credentials"] = "true"
    if method == "OPTIONS":
        # Preflight: какие методы и заголовки разрешены в основном запросе
        headers["Access-Control-Allow-Methods"] = "GET, POST, PUT, PATCH, DELETE"
        headers["Access-Control-Allow-Headers"] = "Authorization, Content-Type"
    return headers


# Security headers
SECURITY_HEADERS = {
    "X-Content-Type-Options": "nosniff",
    "X-Frame-Options": "DENY",
    "Strict-Transport-Security": "max-age=31536000; includeSubDomains",
    "Content-Security-Policy": "default-src 'none'",
}

EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+
quot;) def validate_create_user(data: dict[str, object]) -> dict[str, str]: """Input validation (в FastAPI это Pydantic-модель с EmailStr и min_length).""" errors: dict[str, str] = {} if not EMAIL_RE.match(str(data.get("email", ""))): errors["email"] = "Invalid email format" if len(str(data.get("name", ""))) < 2: errors["name"] = "Must be at least 2 characters" return errors

Итоги

Хорошо спроектированный REST API:

  • Интуитивно понятен
  • Следует стандартам HTTP
  • Имеет предсказуемое поведение
  • Хорошо документирован
  • Безопасен и производителен

Проектирование API - это искусство балансирования между простотой, функциональностью и производительностью. Следуйте принципам REST, но не бойтесь отступать от них, когда это оправдано бизнес-требованиями.

Зарегистрируйтесь бесплатно, чтобы пройти квиз, вести прогресс.