Принципы проектирования REST API

Охватываемые темы: Ресурсы и URL, HTTP методы, Вложенные ресурсы, Коды ответов.

Ресурсы и URL

URL должен обозначать ресурс (существительное), а не действие:

# Плохо (действие в URL)
GET /getTasks
POST /createTask
DELETE /deleteTask/1

# Хорошо (ресурс + HTTP метод = действие)
GET /tasks
POST /tasks
DELETE /tasks/1

HTTP методы

Вложенные ресурсы

GET /projects/5/tasks           # задачи проекта 5
POST /projects/5/tasks          # создать задачу в проекте 5
GET /projects/5/tasks/10        # конкретная задача проекта

Коды ответов

200 OK              — успех (GET, PUT, PATCH)
201 Created         — создан (POST)
204 No Content      — удалён (DELETE)
400 Bad Request     — ошибка в запросе
401 Unauthorized    — не аутентифицирован
403 Forbidden       — нет прав
404 Not Found       — не найдено
422 Unprocessable   — ошибка валидации
500 Server Error    — ошибка сервера

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

GET /tasks?status=todo              # фильтрация
GET /tasks?ordering=-created_at     # сортировка
GET /tasks?page=2&page_size=20      # пагинация
GET /tasks?search=важная+задача     # поиск

Формат ответа

// Список
{
  "count": 42,
  "next": "http://api.example.com/tasks/?page=2",
  "previous": null,
  "results": [
    {"id": 1, "title": "Задача", "status": "todo"}
  ]
}

// Ошибка
{
  "error": "validation_error",
  "message": "Заголовок обязателен",
  "field": "title"
}

Versioning

/api/v1/tasks/    # версия в URL (самый распространённый вариант)
/api/v2/tasks/

# Или через заголовок:
Accept: application/vnd.myapi.v1+json