Введение в REST API

Зачем нужен API

До сих пор наш блог отдавал HTML — готовые страницы для браузера. Но данные блога могут понадобиться и другим программам:

• мобильному приложению;
• фронтенду на React или Vue;
• другому сервису (например, боту в Telegram, который публикует новые посты).

Им не нужен HTML с меню и стилями — им нужны данные. Для этого делают API (Application Programming Interface) — интерфейс, через который программы обмениваются данными.

Что такое REST

REST (Representational State Transfer) — набор принципов построения API поверх HTTP. Главные идеи:

1. Ресурсы. Всё, с чем работает API, — ресурсы: посты, комментарии, пользователи. У каждого ресурса есть адрес (URL).
2. Методы HTTP задают действие. Не /getPosts/ и /deletePost/, а GET /posts/ и DELETE /posts/5/.
3. Представления. Ресурс передаётся в каком-то формате — обычно JSON.
4. Без состояния. Каждый запрос самодостаточен: сервер не хранит «сессию разговора», клиент передаёт всё нужное (например, токен) в каждом запросе.
5. Единообразие. Одинаковые правила для всех ресурсов — API легко изучить.

Ресурсы и адреса

Правила именования: существительные во множественном числе, строчные буквы, вложенность для связанных ресурсов, фильтры — через параметры (/api/posts/?tag=django&page=2).

Коды ответов

JSON

JSON (JavaScript Object Notation) — текстовый формат данных:

{
  "id": 5,
  "title": "Привет, API",
  "author": {"id": 1, "username": "admin"},
  "tags": ["django", "rest"],
  "published": true,
  "rating": null
}

Правила: ключи и строки — только в двойных кавычках, true/false/null — строчными буквами, нет комментариев и висячих запятых. В Python JSON читается и пишется модулем json: объект → dict, массив → list, null → None.

Пример обмена

Запрос:

POST /api/posts/ HTTP/1.1
Host: myblog.ru
Content-Type: application/json
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

{"title": "Новый пост", "body": "Текст"}

Ответ:

HTTP/1.1 201 Created
Content-Type: application/json

{"id": 42, "title": "Новый пост", "body": "Текст", "author": "admin"}

Как пощупать API

• Браузер — для GET-запросов.
• curl в терминале:

curl https://api.github.com/repos/django/django
curl -X POST -H "Content-Type: application/json" -d '{"title": "Тест"}' http://127.0.0.1:8000/api/posts/

• HTTPie (http GET ...) — более удобный curl.
• Postman или Insomnia — графические клиенты.
• Python — библиотека requests:

import requests

resp = requests.get("https://api.github.com/repos/django/django")
print(resp.status_code, resp.json()["stargazers_count"])

Можно ли без фреймворка?

Да — вы уже видели JsonResponse:

def post_list_api(request):
    posts = Post.published.values("id", "title", "publish")
    return JsonResponse({"results": list(posts)})

Но как только появляются создание и валидация, вложенные объекты, права, пагинация, токены и документация, код разрастается. Поэтому в мире Django стандарт — Django REST Framework (DRF), с которым мы начнём работать в следующем уроке.

Итог

• API отдаёт данные (обычно JSON), а не HTML.
• REST: ресурсы с адресами + методы HTTP как действия + коды ответов + отсутствие состояния.
• Хорошие адреса — существительные во множественном числе: /api/posts/5/.
• Для Django стандарт построения API — Django REST Framework.