На каких принципах создаётся API?

# На каких принципах создаётся API?

REST принципы

Современные API строятся на основе REST (Representational State Transfer) архитектуры, сформулированной Роем Филдингом. Основные принципы:

1. Ресурсная архитектура

API должно работать с ресурсами (существительными), а не с действиями (глаголами). Каждый ресурс имеет уникальный идентификатор (URL).

# Правильно ✅ — работаем с ресурсами
GET /api/v1/users           # получить список пользователей
GET /api/v1/users/123       # получить пользователя с ID 123
POST /api/v1/users          # создать пользователя
PUT /api/v1/users/123       # обновить пользователя
DELETE /api/v1/users/123    # удалить пользователя

# Неправильно ❌ — действия в URL
GET /api/v1/getUsers
GET /api/v1/createUser
GET /api/v1/deleteUser/123

2. HTTP методы — семантика операций

Каждый HTTP метод имеет конкретное значение и должен использоваться правильно:

• GET — безопасное чтение (без побочных эффектов, идемпотентно)
• POST — создание нового ресурса (не идемпотентно)
• PUT — полное обновление ресурса (идемпотентно)
• PATCH — частичное обновление (может быть не идемпотентно)
• DELETE — удаление ресурса (идемпотентно)

# Пример с FastAPI
from fastapi import FastAPI

app = FastAPI()

@app.get("/posts/{post_id}")
async def read_post(post_id: int):
    return {"id": post_id, "title": "Post title"}

@app.post("/posts")
async def create_post(title: str, content: str):
    return {"id": 1, "title": title, "content": content}

@app.put("/posts/{post_id}")
async def update_post(post_id: int, title: str, content: str):
    return {"id": post_id, "title": title, "content": content}

@app.patch("/posts/{post_id}")
async def partial_update(post_id: int, title: str = None):
    return {"id": post_id, "title": title or "existing title"}

@app.delete("/posts/{post_id}")
async def delete_post(post_id: int):
    return {"message": f"Post {post_id} deleted"}

3. Коды ответов (HTTP Status Codes)

• 2xx — успех
  • 200 OK — запрос успешен
  • 201 Created — ресурс создан
  • 204 No Content — успех без тела ответа
• 3xx — редирект (301, 302, 304)
• 4xx — ошибка клиента
  • 400 Bad Request — неверные параметры
  • 401 Unauthorized — не авторизован
  • 403 Forbidden — доступ запрещён
  • 404 Not Found — ресурс не найден
• 5xx — ошибка сервера
  • 500 Internal Server Error
  • 503 Service Unavailable

4. Versionирование API

Все публичные endpoints должны быть версионированы:

@app.get("/api/v1/users")      # версия 1
@app.get("/api/v2/users")      # версия 2 (улучшенная схема)

5. JSON как стандартный формат

# Запрос
POST /api/v1/users
Content-Type: application/json
{"name": "John", "email": "john@example.com"}

# Ответ
200 OK
Content-Type: application/json
{"id": 1, "name": "John", "email": "john@example.com"}

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

# Query параметры — это инструмент фильтрации
GET /api/v1/users?role=admin&limit=10&offset=20&sort=created_at

7. Stateless архитектура

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

HATEOAS (гиперссылки в ответе)

Продвинутые API включают гиперссылки для навигации:

{
  "id": 1,
  "name": "John",
  "_links": {
    "self": {"href": "/api/v1/users/1"},
    "all_users": {"href": "/api/v1/users"},
    "update": {"href": "/api/v1/users/1", "method": "PUT"}
  }
}

Эти принципы обеспечивают предсказуемость, масштабируемость и простоту интеграции для клиентов API.