REST API: от схемы до деплоя

Коротко. REST API — способ клиенту и серверу общаться по HTTP через ресурсы (users, orders) и методы (GET, POST, PUT, DELETE). Джуну нужно уметь спроектировать понятные эндпоинты, вернуть правильные статус-коды и написать простой сервис. Ниже — на примере FastAPI.

Что такое REST

REST — набор соглашений об организации API. Ключевая идея: всё крутится вокруг ресурсов, к которым обращаются по URL, а действие задаёт HTTP-метод. Сервер не хранит состояние клиента между запросами (stateless).

Методы и статусы

Важные ошибки: 400 (неверный запрос), 401/403 (нет авторизации/прав), 404 (не найдено), 500 (ошибка сервера).

Проектирование эндпоинтов

• ✅ Существительные во множественном числе: /users, /users/42.
• ✅ Действие — методом, а не в URL: GET /users, а не /getUsers.
• ✅ Вложенность для связей: /users/42/orders.
• ❌ Глаголы в путях и разнобой в именовании.

Пример на FastAPI

from fastapi import FastAPI, HTTPException

app = FastAPI()
users = {1: {"name": "Аня"}}

@app.get("/users/{user_id}")
def get_user(user_id: int):
    if user_id not in users:
        raise HTTPException(status_code=404, detail="Not found")
    return users[user_id]

@app.post("/users", status_code=201)
def create_user(name: str):
    new_id = max(users) + 1
    users[new_id] = {"name": name}
    return {"id": new_id}

FastAPI сам генерирует интерактивную документацию (Swagger) по адресу /docs — удобно для проверки.

Хорошие практики

• ✅ Валидируйте вход и возвращайте понятные ошибки.
• ✅ Версионируйте API (/v1/…), когда он растёт.
• ✅ Документируйте эндпоинты (Swagger/OpenAPI).
• ✅ Не отдавайте лишние поля (пароли, внутренние id).

Частые вопросы

REST или GraphQL джуну?
Начните с REST — он проще и повсеместен. GraphQL добавите при необходимости.

Как тестировать API?
Postman или встроенный Swagger, а также автотесты. См. Postman и API-тестирование и тестирование бэкенда.

PUT или PATCH?
PUT заменяет ресурс целиком, PATCH — частично. Для мелких правок обычно PATCH.