Что такое единообразие интерфейса в REST?

Uniform Interface — Единообразие интерфейса в REST

Uniform Interface (Единообразие интерфейса) — это один из 6 ключевых принципов REST, сформулированных Роем Филдингом. Он означает, что все взаимодействия между клиентом и сервером должны соответствовать согласованному и предсказуемому стилю, независимо от типа ресурса.

4 компонента Uniform Interface

Единообразие интерфейса состоит из 4 подпринципов:

1. Resource Identification (Идентификация ресурсов)

Каждый ресурс должен быть уникально идентифицирован в запросе:

# Правильно: ресурсы идентифицированы через URI
GET /api/v1/users/123          # Получить юзера с ID 123
GET /api/v1/posts/456          # Получить пост с ID 456
GET /api/v1/users/123/posts    # Получить посты юзера 123

# Неправильно: ресурсы скрыты в параметрах или операциях
GET /api/getUser?id=123        # Нарушение: ресурс не в URI
GET /api/users/performAction?action=delete&id=123  # Нарушение: операция в параметре

# FastAPI пример
from fastapi import FastAPI
from typing import Optional

app = FastAPI()

# Единообразное представление ресурсов
@app.get('/api/v1/users/{user_id}')
def get_user(user_id: int):
    return {'id': user_id, 'name': 'John'}

@app.get('/api/v1/posts/{post_id}')
def get_post(post_id: int):
    return {'id': post_id, 'title': 'Post Title'}

# Вложенные ресурсы также идентифицированы через URI
@app.get('/api/v1/users/{user_id}/posts')
def get_user_posts(user_id: int):
    return [{'id': 1, 'title': 'Post 1'}]

2. Resource Manipulation Through Representations (Манипуляция ресурсами через представления)

Клиент манипулирует ресурсами через их представления (JSON, XML и т.д.), а не напрямую взаимодействует с ними:

# Клиент отправляет представление ресурса (JSON)
POST /api/v1/users
Content-Type: application/json

{
    "name": "Alice",
    "email": "alice@example.com",
    "age": 25
}

# Сервер создаёт ресурс на основе этого представления
# Response:
{
    "id": 123,
    "name": "Alice",
    "email": "alice@example.com",
    "age": 25
}

# При обновлении клиент отправляет полное представление
PUT /api/v1/users/123
Content-Type: application/json

{
    "id": 123,
    "name": "Alice Smith",
    "email": "alice@example.com",
    "age": 26
}

# FastAPI реализация
from pydantic import BaseModel

class UserCreate(BaseModel):
    name: str
    email: str
    age: int

class UserResponse(BaseModel):
    id: int
    name: str
    email: str
    age: int

@app.post('/api/v1/users', response_model=UserResponse)
def create_user(user: UserCreate):
    # Создаём ресурс на основе представления от клиента
    new_user = {'id': 123, **user.dict()}
    return new_user

@app.put('/api/v1/users/{user_id}', response_model=UserResponse)
def update_user(user_id: int, user: UserCreate):
    # Обновляем ресурс на основе представления
    updated = {'id': user_id, **user.dict()}
    return updated

3. Self-Descriptive Messages (Самоописываемые сообщения)

Каждое сообщение должно содержать достаточно информации для понимания и обработки без дополнительного контекста:

# Самоописываемое сообщение (все необходимо есть)
GET /api/v1/users/123

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=3600
Last-Modified: Wed, 21 Oct 2025 07:28:00 GMT

{
    "id": 123,
    "name": "Alice",
    "email": "alice@example.com",
    "created_at": "2024-01-15T10:30:00Z"
}

# НЕ самоописываемое (нужен дополнительный контекст)
GET /api/users/123
# Клиент не знает: какая версия API? Какой формат? Когда обновлено?

from fastapi import FastAPI, Header
from datetime import datetime
from email_validator import validate_email

app = FastAPI()

@app.get('/api/v1/users/{user_id}')
def get_user(user_id: int):
    user = {'id': user_id, 'name': 'Alice', 'email': 'alice@example.com'}
    
    return {
        'data': user,
        'meta': {
            'timestamp': datetime.utcnow().isoformat(),
            'api_version': 'v1',
            'charset': 'utf-8'
        }
    }

# Хорошие заголовки - часть самоописания
@app.get('/api/v1/posts/{post_id}')
def get_post(post_id: int):
    return {
        'id': post_id,
        'title': 'My Post',
        'content': 'Content here'
    }

4. HATEOAS (Hypermedia As The Engine Of Application State)

API должен возвращать гиперссылки на связанные ресурсы, позволяя клиенту навигировать без знания всех URI заранее:

# Ресурс с гиперссылками (HATEOAS)
GET /api/v1/users/123

{
    "id": 123,
    "name": "Alice",
    "email": "alice@example.com",
    "links": {
        "self": {"href": "/api/v1/users/123", "method": "GET"},
        "update": {"href": "/api/v1/users/123", "method": "PUT"},
        "delete": {"href": "/api/v1/users/123", "method": "DELETE"},
        "posts": {"href": "/api/v1/users/123/posts", "method": "GET"},
        "all_users": {"href": "/api/v1/users", "method": "GET"}
    }
}

from pydantic import BaseModel
from typing import Dict, List

class Link(BaseModel):
    href: str
    method: str

class UserWithLinks(BaseModel):
    id: int
    name: str
    email: str
    links: Dict[str, Link]

@app.get('/api/v1/users/{user_id}', response_model=UserWithLinks)
def get_user(user_id: int):
    user = {'id': user_id, 'name': 'Alice', 'email': 'alice@example.com'}
    
    links = {
        'self': Link(href=f'/api/v1/users/{user_id}', method='GET'),
        'update': Link(href=f'/api/v1/users/{user_id}', method='PUT'),
        'delete': Link(href=f'/api/v1/users/{user_id}', method='DELETE'),
        'posts': Link(href=f'/api/v1/users/{user_id}/posts', method='GET'),
        'all_users': Link(href='/api/v1/users', method='GET')
    }
    
    return {**user, 'links': links}

Примеры нарушения Uniform Interface

# Плохо: RPC-стиль (не REST)
POST /api/createUser     # Операция в названии
POST /api/deleteUser     # Операция в названии
POST /api/getUser        # GET должен быть, не POST
GET /api/action?op=deleteUser&id=123  # Операция в параметре

# Хорошо: REST-стиль (Uniform Interface)
POST /api/users          # Создание
DELETE /api/users/123    # Удаление
GET /api/users/123       # Получение

Практический пример: Правильный REST API

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Optional

app = FastAPI()

class Article(BaseModel):
    id: Optional[int] = None
    title: str
    content: str
    author: str

# Единообразие: все операции используют правильные HTTP методы
# Все ресурсы идентифицированы через URI
# Клиент манипулирует только представлениями

@app.get('/api/v1/articles')
def list_articles():
    """Получить все статьи"""
    return [
        {'id': 1, 'title': 'Article 1', 'content': '...', 'author': 'John'},
        {'id': 2, 'title': 'Article 2', 'content': '...', 'author': 'Jane'}
    ]

@app.get('/api/v1/articles/{article_id}')
def get_article(article_id: int):
    """Получить конкретную статью"""
    return {'id': article_id, 'title': 'Article', 'content': '...'}

@app.post('/api/v1/articles')
def create_article(article: Article):
    """Создать статью"""
    article.id = 3
    return article

@app.put('/api/v1/articles/{article_id}')
def update_article(article_id: int, article: Article):
    """Обновить статью полностью"""
    article.id = article_id
    return article

@app.patch('/api/v1/articles/{article_id}')
def partial_update(article_id: int, article: Article):
    """Обновить статью частично"""
    article.id = article_id
    return article

@app.delete('/api/v1/articles/{article_id}')
def delete_article(article_id: int):
    """Удалить статью"""
    return {'deleted': article_id}

Преимущества Uniform Interface

✓ Предсказуемость — клиент всегда знает, как взаимодействовать с API ✓ Масштабируемость — легко добавлять новые ресурсы без изменения стиля ✓ Кэшируемость — GET запросы могут кэшироваться (самоописываемые) ✓ Слабая связанность — клиент и сервер могут развиваться независимо ✓ Стандартизация — понимается разработчиками без дополнительного обучения

Резюме: Uniform Interface — это фундаментальный принцип REST, обеспечивающий согласованный и предсказуемый стиль взаимодействия между клиентом и сервером. Он состоит из 4 компонентов: идентификация ресурсов через URI, манипуляция через представления, самоописываемые сообщения и HATEOAS. Единообразие делает API интуитивным и масштабируемым.