Проектирование 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
Используйте существительные, не глаголы
# Плохо
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
Инструменты для документации
- Swagger UI - интерактивная документация
- Postman - коллекции и документация
- Redoc - красивая документация из OpenAPI
- 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, но не бойтесь отступать от них, когда это оправдано бизнес-требованиями.
- PHP - REST API: маршрутизация, валидация, статус-коды - практическая реализация REST на PHP: 201 Created, 422, IDOR, пагинация