Глава 1.4: Структура REST API

Время изучения: 45 минут

---

1. REST API: Архитектура космической станции

Представьте космическую станцию, где каждый модуль имеет:

• Стандартный стыковочный порт (единый интерфейс)

• Четкую специализацию (жилой отсек, лаборатория, хранилище)

• Систему координат (точное расположение)

REST (Representational State Transfer) API работает по тем же принципам:

• Единый интерфейс для всех ресурсов

• Четкое разделение компонентов

• Адресация через URI (космические координаты)

💡 Ключевая идея:

Каждый ресурс (планеты, ракеты, астронавты) имеет уникальный URL-адрес и взаимодействует через HTTP-методы.

---

2. 6 принципов REST в космической аналогии

Принцип REST	Аналог на МКС	Значение для API
Единый интерфейс	Стандартные стыковочные узлы	Одинаковые правила для всех запросов
Stateless	Каждая команда самодостаточна	Сервер не хранит состояние клиента
Кэширование	Локальные запасы провизии	Сохранение частых ответов
Клиент-сервер	Четкое разделение: ЦУП ↔ Станция	Независимое развитие компонентов
Многоуровневость	Ретрансляторы-спутники	Прокси, балансировщики нагрузки
Код по требованию	Загрузка ПО для экспериментов	(Опционально) Передача скриптов

---

3. Ресурсы и URI: Космические координаты

Каждый объект в API — это ресурс с уникальным адресом:

https://api.spacexdata.com/v4/    ← Базовый URL
          rockets/            ← Коллекция ракет
          rockets/5e9d0d95eda69973a809d1ec ← Конкретная ракета (по ID)

Примеры космических ресурсов:

• GET /stars → Список звезд
• GET /stars/sirius → Данные о Сириусе
• POST /satellites → Запустить новый спутник
• PUT /missions/artemis → Обновить миссию

Схема URI-иерархии:

[Базовый URL]
├── /planets          → Коллекция планет
│   ├── /mars         → Ресурс "Марс"
│   └── /venus        → Ресурс "Венера"
└── /launches         → Коллекция запусков
    ├── /upcoming     → Подколлекция
    └── /latest       → Ресурс

---

4. CRUD-операции через HTTP-методы

Операция	HTTP-метод	Пример (Космическая станция)	Ответ сервера
Create	POST	Отправить новый модуль	201 Created
Read	GET	Запросить данные о модуле	200 OK
Update	PUT	Переконфигурировать модуль	200 OK
Delete	DELETE	Отстыковать старый модуль	204 No Content

⚡ Пример кода (Добавление спутника):

import requests

# Используем тестовый сервис, который имитирует создание ресурса
new_post = {
    "title": "New Telescope Launch",
    "body": "Hubble-2 is ready for deployment.",
    "userId": 1
}

# Условный API-ключ для демонстрации заголовков
headers = {
    "Authorization": "Bearer YOUR_DEMO_KEY",
    "Content-Type": "application/json; charset=UTF-8"
}

response = requests.post(
    "https://jsonplaceholder.typicode.com/posts",
    json=new_post,
    headers=headers
)

if response.status_code == 201:
    print("✅ Пост о новом спутнике успешно создан!")
    print("Ответ сервера:")
    print(response.json())
else:
    print(f"❌ Ошибка! Статус: {response.status_code}")

---

5. Версионирование API: Эволюция станции

Как МКС обновляется (Модуль "Заря" → "Наука"), API меняет версии:

• В URL: https://api.spacex.com/v4/rockets
• В заголовках: Accept: application/vnd.spacex-v5+json

Почему важно:

• v1: Базовая функциональность
• v2: Добавлены новые поля
• v3: Изменена структура ответов

⚠️ Совет: Всегда указывайте версию в запросах, иначе "стыковка" может провалиться!

---

6. Гипермедиа (HATEOAS): Навигация в космосе

Ответ API содержит ссылки на связанные ресурсы — как карта станции:

{
  "id": "iss",
  "name": "Международная Космическая Станция",
  "crew": 7,
  "_links": {
    "self": { "href": "/stations/iss" },
    "modules": { "href": "/stations/iss/modules" },
    "schedule": { "href": "/stations/iss/schedule" }
  }
}

---

Квиз для закрепления

1. REST расшифровывается как:

a) Rocket Engine System Transfer b) Representational State Transfer c) Remote Space Technology

2. Принцип "Stateless" означает:

a) Сервер хранит историю запросов b) Каждый запрос самодостаточен c) Данные передаются только через SSL

3. URI для получения данных о ракете Falcon Heavy:

a) POST /rockets/falcon-heavy b) GET /falcon-heavy c) GET /rockets/falcon-heavy

4. Метод для полного обновления ресурса:

a) PATCH b) POST c) PUT

5. HATEOAS в API — это:

a) Система ссылок на связанные ресурсы b) Протокол шифрования c) Язык запросов

Проверить

---

🚀 Итог главы:

REST API — это стандартизированная "архитектура космической станции" для веб-сервисов. Запомните:

• Ресурсы = Объекты (ракеты, планеты)
• URI = Координаты объектов
• HTTP-методы = Команды управления
• Версии = Модернизации станции

Финал подготовки! В следующей главе мы запустим "тестовый зонд" — научимся тестировать API через Postman.

📌 Практика: Изучите структуру SpaceX API и попробуйте выполнить:

GET https://api.spacexdata.com/v4/launches/latest — обратите внимание на URI и JSON-структуру!