Охватываемые темы: Ресурсы и URL, HTTP методы, Вложенные ресурсы, Коды ответов.
Ресурсы и URL
URL должен обозначать ресурс (существительное), а не действие:
# Плохо (действие в URL)
GET /getTasks
POST /createTask
DELETE /deleteTask/1
# Хорошо (ресурс + HTTP метод = действие)
GET /tasks
POST /tasks
DELETE /tasks/1
HTTP методы
| Метод | Действие | Идемпотентный |
|---|---|---|
| GET | Получить | Да |
| POST | Создать | Нет |
| PUT | Заменить полностью | Да |
| PATCH | Обновить частично | Да |
| DELETE | Удалить | Да |
Вложенные ресурсы
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
💬 Комментарии (0)
Комментариев пока нет
Станьте первым, кто поделится мнением об этой статье!